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To the Reader 



This manual is part of the BASIC documentation set. This set of manuals was designed to let you learn 
and use BASIC regardless of your prior experience with computers. The documentation set includes: 

For the beginner: 

• Introduction to BASIC 

• BASIC for Beginners 

• More BASIC for Beginners 
For all systems: 

• BASIC User's Guide 

• BASIC Reference Manual 

• BASIC Pocket Reference Guide 
For specific systems: 

• BASIC on RSTS/E Systems 

• BASIC on RSX-1 1 M I M-PLUS Systems 

• BASIC on VAX I VMS Systems 
For the system manager: 

• BASIC-PLUS-2 RSTS/E Installation Guide and Release Notes 

• BASIC-PLUS-2 RSX-1 1M /M-PLUS Installation Guide and Release Notes 

• VAX- 7 1 BASIC Installation Guide and Release Notes 

For the beginner, Introduction to BASIC explains the fundamentals of the BASIC language and shows 
how to use BASIC to solve programming problems. BASIC for Beginners and More BASIC for 
Beginners lead the reader step-by-step through planning and writing several practical programs that 
teach BASIC programming techniques. In addition, the first chapter of the system-specific user's guide 
tells you how to log on to your computer system, create and execute programs, and do simple file 
operations such as printing, typing, and deleting files. 
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For programmers who are more familiar with BASIC, the BASIC User's Guide and the system-specific 
user's guides include a complete explanation of BASIC and how to use it on your system. If you need 
information on a particular feature or statement, the BASIC Reference Manual describes the format of 
each BASIC command or keyword individually. 

The BASIC documentation set has several new features that let you find information quickly and 
easily. Each manual has its own index (with instructions on its use) and the BASIC Reference Manual 
has a master index to the entire documentation set. For quick reference the BASIC Pocket Reference 
Guide provides a brief explanation of all BASIC commands and functions. Similar information is also 
available at the computer terminal from the BASIC HELP facility. 

The following pages describe the function of this particular manual. We welcome your comments 
and encourage you to use the Reader's Comments Form provided at the back of this book. 

Document Objectives 

This manual describes the language elements and syntax of Version 2 of VAX-11 BASIC and 
BASIC-PLUS-2. The term BASIC is used generically in this manual to refer to both VAX-/ 7 BASIC 
and BASIC-PLUS-2. The term VAX-1 1 BASIC refers specifically to VAX-/ / BASIC as implemented on 
VAX/VMS systems. BASIC-PLUS-2 refers specifically to BASIC-PLUS-2 as implemented on RSTS/E, 
RSX-1 1 M, and RSX-1 1 M-PLUS systems. 

Note 

For your convenience, examples, formats, or rules specific to VAX-11 BASIC, 
BASIC-PLUS-2, or BASIC-PLUS-2 on RSTS/E or RSX-1 1M /M-PLUS are identified by 
a marginal symbol: 




(vax> indicates VAX-1 1 BASIC only. 
(Bra) indicates BASIC-PLUS-2 only. 
(rsts) indicates BASIC-PLUS-2 on RSTS/E systems. 
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indicates BASIC-PLUS-2 on RSX-1 ? M I M-PLUS systems. 



Intended Audience 

This manual should be used by programmers familiar with computer concepts and the BASIC lan- 
guage. It is a reference manual to be used in conjunction with the BASIC user's guides. 

Document Structure 

This manual consists of six parts, two appendixes, and a master index to the BASIC documentation 
set. With the exception of Part I, BASIC language elements are arranged in alphabetical order within 
each part; each language element begins on a separate page. A sample format page is included on 
page xiv. 

Part I Describes BASIC program elements and structure. 

Part II Describes BASIC compiler commands. 
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Part II! Describes BASIC compiler directives. 

Part IV Describes BASIC statements. 

Part V Describes BASIC functions. 

Part VI Describes BASIC-PLUS-2 debugger commands. 

Appendix A Lists reserved keywords. 

Appendix B Summarizes program and subprogram coding conventions. 

This manual also includes three tabbed dividers for convenient reference: 

• The first divider summarizes the conventions used in this manual. 

• Thp <;ecnnr| HivirW lictc mnct RAQIf"" Up»/»A//->r,-(c k>, (. , n ,~+:^ n 

• The third divider precedes the Master Index and describes its use. 
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Sample Format Page 
ENTRY NAME 

1.0 ENTRY NAME 

Function 

Describes the entry's function or effect. 

Format 

A format shows the syntax of a language element. When you have a choice of formats, the 
formats are named for clarity. When a format is named General, it applies to both VAX- 7 1 
BASIC and BASIC— PLUS— 2. Format components are explained in syntax and general rules. 
When a language element has more than one format, formats are referred to by name. 
Some formats are divided into two parts. The first part, in the top portion of the box, shows 
the general elements and order of the format. 

The second part of the format, in the lower portion of the box, shows the components 
and order of the individual elements in the general format. 

Syntax Rules 

Syntax rules tell you how to order format elements to form clauses or statements. They also 
impose restrictions or relax restrictions implied by the format. 

General Rules 

General rules define the semantics of the entry and the entry's effect on program execution or 
compilation. 

Examples 

This section presents one or more sample program lines. All examples work for both VAX-1 1 BASIC 
and BASIC-PLUS-2 unless otherwise noted. 
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Conventions 

Formats present the correct syntax for writing BASIC source code. You must order syntax elements as 
shown in the format unless the syntax rules indicate otherwise. 

Syntax formats consist of BASIC keywords, metalanguage mnemonics, and punctuation symbols. 
Metalanguage mnemonics are symbolic derivations of BASIC objects or structures. The tabbed 
divider that follows this section lists the most frequently used mnemonics and their meanings, as well 
as the most frequently used punctuation symbols. 

Note 

BASIC keywords are always capitalized in this manual and must be spelled exactly as 
shown. Mnemonics are in lowercase letters in formats and are italicized in the syntax 
and general rules. 

Some metalanguage mnemonics are derived directly from BASIC keywords. For example: 



• Map 


From MAP 


• Com 


From COMMON 


• Func 


From FUNCTION 


• Def 


From DEF 


•Sub 


From SUB 


Others are 


abbreviated forms of wc 


• Vbl 


For variable 


• Unsubs 


For unsubscripted 


• Subs 


For subscripted 


•Str 


For string 


• Const 


For constant 


• Exp 


For expression 


• Nam 


For name 


• Cond 


For conditional 


• Int 


For integer 


• File-spec 


For file-specification 



• Data-type For data-type 

Most mnemonics used in formats are combinations of mnemonics. For example: 

• Const-nam Is a constant name. 

• Sub-nam Is the name of a SUB subprogram. 

• Unsubs-vbl Is an unsubscripted variable. (continued on next page) 
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• Int-exp Is an integer expression. 

• Cond-exp Is a conditional expression. 

• Str-unsubs-vbl Is a string unsubscripted variable. 

Mnemonics are combined in this way to indicate exactly what type of object or structure BASIC 
expects. Some BASIC statements, for example, allow you to specify any type of variable (string or 
numeric) in the format, while others allow only a numeric variable (integer or floating-point), a string 
variable, an integer variable, or a floating-point variable. 

Thus, the uncombined form of the variable mnemonic (vb!) in a format means that you can use any 
type of variable (string or numeric). A combined variable mnemonic (such as str-vbl, num-vbl, or 
int-vbl) in a format means that you can specify only a particular type of variable. 

Within formats, mnemonics are either simple or complex. Simple mnemonics identify a format 
element (such as an expression, a variable, or a name) that needs no further definition. For example: 



EXTERNAL data-type CONSTANT const-nam,. 



The mnemonics in this format need no further definition. The EXTERNAL keyword must be followed 
by a data-type, the CONSTANT keyword, and then a const-nam. The comma and ellipsis (...), as 
defined in the Punctuation Symbols Table, indicate that you can specify more than one const-nam. 
The data-type mnemonic is defined in the Mnemonics Table as a BASIC data-type keyword, and 
const-nam is defined as a constant name. Restrictions to the use of data-type keywords in the 
EXTERNAL statement are specified in the syntax rules. 

Complex mnemonics identify a format element (such as a parameter passing mechanism or a state- 
ment clause) that has more than one component. Complex mnemonics are further defined in the 
lower portion of the format box by simple mnemonics. For example: 

Format 



Variables 




DECLARE data-type decl-item [, [ data-type ] decl-item ]... 




DEF Functions 




DECLARE data-type FUNCTION { def-nam [ ( [ def-param ],.. 


) 1 },-. 


Named Constants 




DECLARE data-type CONSTANT { const-nam = const },... 




decl-item: 


unsubs-vbl-nam 
array-nam ( int-const,... ) 






def-param: [ data-type ] 





XVI 



When you look at the upper portion of this format, you can see that a data-type keyword must follow 
the DECLARE statement and that a decl-item must follow the data-type keyword. Ded-item is a 
complex mnemonic that is then further defined in the lower portion of the box. There you can see 
that a decl-item can be a simple variable name or an array name followed by parentheses and integer 
constants separated by parentheses. The portion of the upper format in brackets indicates that v ou can 
specify another data-type keyword and another array name or simple variable name. The comma and 
ellipsis (...), as defined on the tabbed divider in this section, indicate that you can continue adding 
data-type keywords and array names or simple variable names. 

This type of format unfolds the syntax of BASIC language elements and indicates the type of element 
BASIC expects to receive. 

Note 

In most cases, BASIC signals an error if the syntax element does not exactly match the 
indicated format. In other instances, particularly with numeric elements, BASIC con- 
verts the numeric element you specify to the type of numeric element it expects to 
receive. These instances are noted in the syntax rules. 

Multiple occurrences of mnemonics in a format are numbered to prevent confusion. Vbl3, for exam- 
ple, is the third unique variable in a general format and is referred to as vbl3 in the syntax and general 
rules. 

The most frequently used punctuation symbols and metalanguage mnemonics are listed and 
described on the first tabbed divider in this manual. Less frequently used mnemonics and most 
complex mnemonics are defined as they occur in syntax formats. 

Please use the Reader's Comments Form in the back of this book to report errors or to make sugges- 
tions for future documentation releases. 
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Conventions 

Syntax Mnemonics 



Mnemonic 



Definition 



exp An expression 

vbl A variable 

unsubs Unsubscripted; used with the variable mnemonic to indicate a simple variable, as opposed to an array 

element 

subs Subscripted; used with the variable mnemonic to indicate an array element; the element's position in the array 

is specified by subscripts enclosed in parentheses and separated by commas 

array An array; syntax formats indicate whether you can specify bounds and dimensions, or just dimensions 

const A constant value 

lit A literal value, in quotation marks; a literal is always a constant, but a constant may be named, so constants 

are not always literals 

num A numeric value 

real A floating-point value 

int An integer value 

str A character string 

cond Conditional; used with the expression mnemonic to indicate that an expression can be either logical or 

relational 

log Logical; used with the expression mnemonic to indicate a logical expression 

rel Relational; used with the expression mnemonic to indicate a relational expression 

lex Lexical; used to indicate a component of a compiler directive 

target The target point of a branch statement; used to indicate that the target point can be either a program line 

number or a statement label 

lin-num A program line number 

label An alphanumeric statement label 

item Allowable BASIC objects, such as variables, data types, and parameters; allowable objects are defined in 

formats as they occur 

nam Name; indicates the declaration of a name or the name of a BASIC structure, such as a SUB subprogram 

com Specific to a COMMON 

def Specific to a DEF 

func Specific to a FUNCTION subprogram 

map Specific to a MAP 

sub Specific to a SUB subprogram 

chnl An I/O channel associated with a file 

data-type A data-type keyword 

file-spec A file-specification 

file-nam A file name 



Punctuation Symbols 
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Definition 



I 1 Rrarkptc pnrlnsp an nntinnal nortion nt a tnrmat KrarkpK arnnnrl vprtiraHv starker) entries indicate that VOU 

can select one of the enclosed elements. You must include all punctuation as it appears in the brackets. 

{ } Braces enclose a mandatory portion of a general format. Braces around vertically stacked entries indicate 

that you must choose one of the enclosed elements. Braces also group portions of a format as a unit. You 
must include all punctuation as it appears in the braces. 

An ellipsis indicates that the immediately preceding language element can be repeated. An ellipsis following 
a format unit enclosed in brackets or braces means that you can repeat the entire unit. If repeated elements 
or format units must be separated by commas, the ellipsis is preceded by a comma (,...). 



Definitions 

In this manual, the following definitions apply: 

BASIC The term BASIC refers to Version 2 of both VAX-/ 7 BASIC and PDP-11 

BASIC-PLUS-2. 

BASIC-PLUS-2 The term BASIC-PLUS-2 refers specifically to Version 2 of PDP-11 
BASIC-PLUS-2 as implemented on RSTS/E, RSX-11M, and RSX-11M-PLUS 
systems. 



Cannot 

Cursor 
or 
cursor position 

Must 



Cannot indicates than an operation cannot be performed and that an attempt to 
perform the operation causes BASIC to signal an error. 

Cursor or cursor position refers to a terminal's print mechanism. It can be the 
flashing cursor on a video display terminal or the print head on a hard-copy 
terminal. 

Must indicates that an operation must be performed and that failure to perform the 
specified operation causes BASIC to signal an error. 



Program module A program module is a BASIC main program, a SUB subprogram, or a FUNCTION 
subprogram. 

Subprogram A separately compiled program module that must be linked or task-built with the 

main program. 

Subroutine A subroutine is a block of code accessed by a GOSUB or ON GOSUB statement. It 

is always in the same program module as the statement that accesses if. 

VAX-1 1 BASIC The term VAX-1 1 BASIC refers specifically to Version 2 of VAX-1 1 BASIC as 
implemented on VAX/VMS systems. 



Functional List of BASIC Keywords 



Arrays 


Error Handling 


NOECHO 


END SUB 


DET 


FDI 


PRINT USING 


CVIT CI ims — ris-^ i 




i_i\i_ 
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DIMENSION 


ERN$ 


RCTRLC 


EXIT SUB 


MAT 


ERR 


RCTRLO 


EXTERNAL 


MAT INPUT 


ERT$ 


RECOUNT 


FUNCTION 


MAT LIN PUT 


ON ERROR GO BACK 


TAB 


LOC 


MAT PRINT 


ON ERROR GOTO 




SUB 


MAT READ 


ON ERROR GOTO 


Numbers 




NUM 


RESUME 


ABS 


Strings 


NUM2 




ATN 


EDITS 


Data Conversion 


Function Definition 

DEF 


COMP% 
COS 


FORMATS 
INSTR 


ASCII 


END DEF 


DECIMAL 


LEFTS 


CHANGE 


END FUNCTION 


EXP 


LEN 


CHR$ 


EXIT DEF 


FIX 


LSET 


NUM$ 


EXIT FUNCTION 


INT 


MID$ 


NUM1$ 


EXTERNAL 


INTEGER 


POS 


STR$ 


FUNCTION 


LOG 


RIGHTS 


VAL 




LOG 10 


RSET 


VAL% 


I/O to Files 


MAG 


SEG$ 


Data Definition 


CLOSE 
DELETE 


RANDOMIZE 
REAL 


SPACES 
STRINGS 


COMMON 


FIND 


RND 


TRM$ 


DECLARE 


FREE 


SGN 


XLATE 


DIMENSION 


GET 


SIN 




MAP 


INPUT # 


SQR 


String Arithmetic 


MAP DYNAMIC 


INPUT LINE # 


SWAP% 


DIF$ 


MOVE 


KILL 


TAN 


PLACES 


RECORD 


LINPUT# 




PRODS 


REMAP 


MAR 


Program Control 


QUO$ 


Data Formatting 


MARGIN 
MOVE 


END 

EXIT LOOP 


SUMS 


FORMATS 


NAME AS 


FOR 


Value Assignmen 


PRINT USING 


OPEN 


GOSUB 


DATA 




PRINT # 


GOTO 


LET 


Data Typing 


PUT# 


IF 


LSET 


COMMON 


RECOUNT 


ITERATE 


READ 


DECLARE 


RESTORE # 


ON GOTO 


RESTORE 


DEF 


SCRATCH 


RETURN 


RSET 


DIMENSION 


UNLOCK 


SELECT 




EXTERNAL 


UPDATE 


SLEEP 




FUNCTION 




STOP 




MAP 


I/O to Terminals 


UNLESS 




OPTION 


CCPOS 


UNTIL 




SUB 


CTRLC 


WAIT 






ECHO 


WHILE 




Date and Time Conversion 


INPUT 


Program Segmentation 




DATES 


INPUT LINE 


CALL 




TIME 


LINPUT 


CHAIN 




TIMES 


MAR 


END FUNCTION 





PARTI 

Program Elements 

and Structure 



1.0 Elements of a BASIC Program 

A BASIC program is a series of program lines that contain instructions for the BASIC compiler. These 
instructions are in the form of BASIC statements. Program lines contain the BASIC keywords, opera- 
tors, and operands that make up a BASIC program. 

The first line of a BASIC program must begin with a line number. The program lines that follow may 
contain: 

• Line numbers or labels 

• Statements 

• Optional compiler directives 

• Optional comment fields 

• Line terminator (carriage return) 

1 .1 Line Numbers 

Every BASIC statement must be associated with a line number. Thus, the first element in a BASIC 
program must be a line number. A line number must be an integer between 1 and 32767, inclusive. 
A space or tab terminates the line number. Embedded spaces, tabs, and commas within line numbers 
are invalid. 

A line number followed by a carriage return does not constitute a BASIC program line. A program line 
must contain a statement or a comment field. Comment fields are discussed in Section 2.1. A new 
line number or a carriage return terminates a BASIC program line. 

A program line can contain any number of text lines; however, a text line cannot exceed 255 
characters in VAX-/? BASIC and BASIC-PLUS-2 on RSTS/E systems, and 132 characters in 
BASIC-PLUS-2 on RSX-1 1 M I M-PLUS systems. 
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The BASIC language uses line numbers to: 

• Indicate the order of statement execution 

• Provide control points for branching 

• Help in debugging and updating programs 

• Find the location of run-time errors 

• Resume processing after an error has been handled 

Therefore, each line number must be unique. BASIC ignores leading spaces, tabs, and zeros in line 
numbers. 

1.2 Labels 

A label is a 1- to 31-character name that immediately precedes a statement. It may immediately 
follow a line number. The label logically identifies a statement or block of statements. The label name 
must conform to the rules for naming variables, described in Section 6.1. The label name must be 
separated from the statement it labels with a colon (:). For example: 

100 Yes_ routine: PRINT "Your answer is YES," 

The colon is not part of the label name. It tells BASIC that the label is being defined rather than 
referenced. Consequently, the colon is not allowed when you use a label to reference a statement. 
For example: 

200 GOTO Yes. routine 

The BASIC language uses labels to: 

• Provide control points for branching 

• Help in debugging programs 

• Help in maintaining and updating programs 

You can reference a label anywhere you can reference a line number, with three exceptions: 

• You cannot compare the value returned by the ERL function (the line number associated with the 
program line where the last error occurred) with a label. 

• You cannot use the RESUME statement to reference a label. 

• You cannot reference a label in an IF-THEN-ELSE statement without using the keyword GOTO or 
GO TO. You can use the implied GOTO form only to reference a line number. For example: 

100 if K = BI 

THEN 1000 
ELSE 1050 

200 IF A$ = "YES" 

THEN GOTO Yes 
ELSE GOTO No 
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Because the first statement references a line number, the GOTO keyword is not required; the second 
statement references a label, so the GOTO keyword is required. 

1.3 Statements 

A BASIC statement consists of a statement keyword and optional operators and operands. For 
example: 

400 LET AX = 534Z + CSUMX - DIF%) 
PRINT AX 

The first statement assigns a value to the integer variable A%. The PRINT statement causes BASIC to 
display the value of A% on your terminal. 

A statement is either executable or nonexecutable: 

• Executable statements perform operations (for example, PRINT, GOTO, and READ). 

• Nonexecutable statements describe the characteristics and arrangement of data, specify usage infor- 
mation, and serve as comments in the source program (for example, DATA, DECLARE, and REM). 

BASIC can accept and process one statement on a line of text, several statements on a line of text, 
multiple statements on multiple lines of text, and single statements continued over several lines of 
text. Each line of program text is associated with the last specified line number. 

Multi-statement and continuation lines are discussed in Sections 1 .3.2 and 1 .3.3. 

1.3.1 Keywords 

A keyword is a reserved element of the BASIC language. Every statement except LET and empty 
statements must begin with a keyword. BASIC uses keywords to: 

• Define data and user identifiers 

• Perform operations 

• Invoke built-in functions 

Note 

Keywords are reserved words and cannot be used as variable names or as names for 
MAP or COMMON areas. 

Keywords cannot be used in any context other than as BASIC keywords. STRINGS = "YES", for 
example, is invalid because STRINGS is a reserved BASIC keyword. Appendix A in this manual 
contains a list of BASIC reserved keywords. 

A BASIC keyword cannot have embedded spaces and cannot be split across lines of text. There must 
be a space, tab, or special character such as a comma between the keyword and any other variable or 
operator. 
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Some keywords use two words. In this case, their spacing requirements vary, as shown in Table 1. 
Table 1 : Keyword Space Requirements 



Optional Space 


Mandatory Space 


No Space 


CO SUB 


BY DESC 


FNEND 


GOTO 


BYREF 


FNEXIT 


ON ERROR 


BY VALUE 


FUNCTIONEND 




END DEF 


FUNCTIONEXIT 




END FUNCTION 


NOECHO 




END GROUP 


NOMARGIN 




END IF 


SUBEND 




END RECORD 


SUBEXIT 




END SELECT 






END SUB 






EXIT DEF 






EXIT FUNCTION 






EXIT SUB 






INPUT LINE 






MAP DYNAMIC 






MAT INPUT 






MAT LINPUT 






MAT PRINT 






MAT READ 





1.3.2 Single-Statement Lines and Continued Statements 

A single-statement line consists of one statement on one numbered line or one statement continued 
over two or more text lines. For example: 



100 



PRINT B * C / 12 



This single-statement line has a line number, keyword (PRINT), operators (*, /), and operands (B C 
and 12). 

You can have a single statement span several text lines by typing an ampersand (&) and a carriage 
return. For example: 



100 OPEN "SAMPLE.DAT" AS FILE 2% , 
SEQUENTIAL VARIABLE* 
MAP ABC 



The ampersand must come immediately before the carriage return in VAX-1 1 BASIC. BASIC-PLUS-2 
ignores spaces or tabs that follow the ampersand and precede the carriage return. For compatibility, 
DIGITAL recommends that you type the carriage return immediately after the ampersand. 

The ampersand continuation character may be used but is not required for continued REM state- 
ments. The following example is valid: 

100 REM This is a remark 

And this is also a remarK 
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You can continue any BASIC statement, but you cannot continue a string literal or BASIC keyword. 
For example, BASIC returns the error message "Unterminated string literal" if you try to print the 
following: 

100 PRINT "FEE-FIE- & 

FOE-FUM" 

This example is valid: 

200 PRINT "FEE-"! & 

"FIE-" i 8= 

"F0E-"5 & 
"FUM" 

A more efficient way to continue string literals is to use the string concatenation operator: 

100 PRINT "FEE-" & 

+ "FIE-" & 

+ "F0E-" & 

+ "FUM" 

BASIC concatenates the four string literals at compile time and stores them as one string. When the 
PRINT statement executes, BASIC displays the one concatenated string literal rather than four sepa- 
rate string literals, thereby causing your program to execute faster and more efficiently. 

Continued statements do not have line numbers, although the compiler counts and numbers them as 
sublines. 

1.3.3 Multi-Statement Lines 

Multi-statement lines contain several statements on one line of text or multiple statements on separate 
lines of text. All the statements on a multi-statement line are associated with a single line number. 

Multiple statements on one line of text must be separated by backslashes (\). For example: 

400 PRINT A \ PRINT V \ PRINT G 

Because all statements are on the same program line, any reference to line number 400 refers to all 
three statements and execution begins with the first statement on the line. That is, BASIC cannot 
execute the second statement without executing the first statement. 

A statement that unconditionally transfers control to another program line should always be the last 
statement on a multi-statement line. Otherwise, the statements that follow the statement transferring 
control will never execute. The following program line, for example, will execute, but it is not 
recommended: 

200 PRINT A \ GOTO 410 \ PRINT B 

BASIC prints the value of A and then branches to line 410. The statement PRINT B will never execute. 
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You can also write a multi-statement program line that associates all statements with a single line 
number by ending each statement with an ampersand (&) and a carriage return and preceding the 
next statement with a backslash. For example: 



400 PRINT A & 
\ PRINT M & 
\ PRINT G 



Because programs written in this format tend to be cluttered and hard to read, BASIC allows you to 
associate multiple statements with a line number by placing each statement on a separate line without 
using the ampersand or backslash. This format requires only a space or tab at the beginning of each 
new line of text. BASIC assumes that such an unnumbered line of text is either a new statement or an 
IF statement clause. For example: 

400 PRINT A 
PRINT B 
PRINT "FINISHED" 

In this example, each line of text begins with a BASIC statement and each statement is associated with 
line number 400. 

BASIC also recognizes IF statement keywords on a new line of text and associates such keywords with 
the preceding IF statement. For example: 

100 IF (A* = "YES") OR (A$ = "Y") 
THEN PRINT "You typed YES" 
ELSE PRINT "You typed NO" 

STOP 
END IF 

The BASIC compiler listing file numbers the lines associated with line number 100 as they occur The 
VAX-1 7 BASIC listing file looks like this: 





i 


100 


IF (A* = "YES") OR (A* = "Y") 


/\ 


2 




THEN PRINT "You typed YES" 


VAX> 


3 




ELSE PRINT "You typed NO" 


Ss 


a 




STOP 




5 




END IF 



The BASIC-PLUS-2 listing file looks like this: 



00001 


100 


IF (A$ = "YES") OR (A* = "Y 


00002 




THEN PRINT "You typed YES" 


00003 




ELSE PRINT "You typed NO" 


00004 




STOP 


00005 




END IF 



Each statement has a number that indicates its position in the line. The BASIC compiler counts the 
statements in a multi-statement line to locate compile-time errors. You cannot use statement numbers 
as targets of branch statements. Targets of branch statements such as GOTO must be a line number or 
a label. 
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You can use any BASIC statement in a multi-statement line. However, a REM or DATA statement 
must be the last statement on a multi-statement line. This is because the compiler: 

• Ignores all text following a REM keyword until it reaches a new line number. 

• Treats aii text following a DATA keyword as data untii it reaches a new iine number; thus, every 
DATA statement in your program has to have its own line number. 

Because a leading space or tab not followed by a line number implies a new statement in a multi- 
statement line, compiler commands and immediate mode statements cannot be preceded by a space 
or tab. If you enter a compiler command or immediate mode statement, you cannot add more 
continuation lines to the last program line. If you attempt to do so, BASIC signals the error "unknown 
command input". 

1.4 Compiler Directives 

Compiler directives are instructions in a program that tell BASIC to perform certain operations as it 
compiles the program. With compiler directives, you can: 

• Place program titles and subtitles in the header that appears on each page of the listing file 

• Place a program version identification string in both the listing file and object module 

• Start or stop the accumulation of listing information for selected parts of a program 

• Start or stop the accumulation of cross-reference information for selected parts of a program 

• Include BASIC code from another source file 

• Conditionally compile parts of a program 

• Terminate compilation 

• Include CDD record definitions in a BASIC program (VAX-1 7 BASIC only) 

All compiler directives: 

• Must begin with a percent sign 

• Can be preceded by an optional line number 

• Must be the only text on the line (except for %IF-%THEN-%ELSE-%END-%IF) 

• Must be preceded by a space, tab, or line number 

• Cannot appear within a quoted string 

See the BASIC User's Guide and Part III in this manual for more information on compiler directives. 

1 .5 Line Terminators 

In the BASIC environment, a carriage return /line feed combination (®) followed by an optional 
space or tab and a new line number ends a BASIC program line. An ampersand followed by a 
carriage return ends a line of text but not the program line. All statements between the first line 
number and the next line number are associated with the first line number. 
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1.6 Lexical Order 

Lexical order refers to the order in which BASIC compiles statements in a program, in general terms, 
BASIC compiles program lines in sequential order from the lowest to the highest line number. Thus^ 
statement A precedes statement B if the line number with which statement A is associated is lower 
than the line number with which statement B is associated. If both statements are associated with the 
same iine number, statement A precedes statement B only if it physically precedes statement B or 
appears to the left of statement B. BASIC processes statements on a line of text from left to right and 
lines of text from top to bottom. 

Some BASIC statements, such as comments and MAP declarations, are nonexecutable. If program 
control passes to a nonexecutable statement, BASIC executes the first statement that lexically follows 
the nonexecutable statement. 

2.0 Program Documentation 

Documentation clarifies and explains source program structure. You can provide such explanations 
with: 

• Comment fields 

• REM statements 



2.1 Comment Fields 

A comment field begins with an exclamation point (!) and ends with a carriage return. You supply text 
after the exclamation point to document your program. BASIC does not execute text in a comment 
field. For example: 

100 ! FOR loop to initialize list Q 

FOR I = 1 TO 10 

Q(I> = ! This is a comment 
NEXT I 
! List now initialized 

BASIC executes only the FOR loop. The comment fields, preceded by exclamation points, do not 
execute. 

Comment fields help make your program more readable and allow you to format your program into 
readily visible logical blocks. They can also serve as target lines for GOTO and GOSUB statements: 

10 

Square root program 

INPUT 'Enter a number' iA 
PRINT 'SQR of 'iAi'is '!SQR<A> 

More square roots? 

INPUT 'Type "Y" to continue* a carriage return to quit'jANS* 
GOTO 10 IF ANS* = 'Y' 

! 

99 END 
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You can also use an exclamation point to terminate a comment field, but this practice is not recom- 
mended. Therefore, you should make sure that there are no exclamation points in the comment field 
itself; otherwise, BASIC treats the text remaining on the line as source code. 

Note 

Comment fields in DATA statements are invalid; the compiler treats the comments as 
additional data. 



2.2 REM Statements 

A REM statement begins with the REM keyword and ends when BASIC encounters a new line 
number. The text you supply between the REM keyword and the next iine number documents your 
program. Like comment fields, REM statements do not affect program execution. BASIC ignores all 
characters between the keyword REM and the next line number. Therefore, the REM statement can be 
continued without the ampersand continuation character and should be the only statement on the 
line or the last of several statements in a multi-statement line: 



10 REM This is an example 
20 A = 5 

B=10 

REM A equals 5 
B equals 10 
30 PRINT A» B 



The REM statement is nonexecutable. When you transfer control to the line number of a REM 
statement, BASIC executes the next executable statement that lexically follows the referenced line. 
For example: 



1 ri DCM JLM. On <■ -* « s -a « « * i-t w «. tf ** - v 

20 INPUT 'Enter a number' >A 

PRINT 'SQR of 'SAI'is 'SSQR(A) 

INPUT 'Type "Y" to continue* a carriase return to suit'iANS* 

GOTO 10 IF ANS* = 'Y' 
40 END 



When the conditional GOTO statement in line 20 transfers program control to line 10, BASIC ignores 
the REM comment on line 10 and continues program execution at line 20. 



Note 

Because BASIC treats all text between the REM statement and the next line number as 
commentary, REM should be used very carefully in programs that follow the implied 
continuation rules. Program statements intended for execution will not execute when 
they are inside a REM statement. DIGITAL recommends the use of comment fields (!) 
for program documentation in programs formatted with implied continuation lines. 



BASIC Reference Manual 



2.3 Empty Statements 

Empty statements consist of a line number and an exclamation mark followed by optional text, a line 
terminator and a new line number. For example: 

100 ! 

i FOR loop to initialize list 

! 

200 FOR I = 1 TO 10 

0(1) = ! This is a comment 

NEXT I 
300 ! 

! List is now initialized 

Lines 100 and 300 are empty statements. 

3.0 BASIC Character Set 

BASIC uses the full ASCII character set. This includes: 

• The letters A through Z, both upper- and lowercase 

• The digits through 9 

• Special characters 

Appendix C in BASIC on VAX/VMS Systems, BASIC on RSX-1 1M/M-PLUS Systems, and BASIC on 
RSTS/E Systems contains the full ASCII character set and character values. 

The compiler: 

• Does not distinguish between upper- and lowercase letters except in string literals or within a DATA 
statement 

• Does not process nonprinting characters unless they are part of a string literal 

• Does not process characters in REM statements or comment fields 
In string literals, BASIC processes: 

• Lowercase letters as lowercase 

• Nonprinting characters 

The ASCII character NUL (ASCII code 0) and line terminators cannot appear in a string literal. Use the 
CHR$ function or explicit literal notation to use this character and terminators. 

You can use nonprinting characters in your program, for example, in string constants, but to do so 
you must use: 1) a predefined constant such as ESC and DEL, 2) the CHR$ function to specify an 
ASCII value, or 3) explicit literal notation for character constants. See Section 5.4 in this manual for 
more information on explicit literal notation. See the BASIC User's Guide for more information on 
predefined constants and the CHR$ function. 

4.0 BASIC Data Types 

All data in a BASIC program has a specific data type that determines how many bits of storage should 
be considered as a unit and how the unit is to be interpreted and manipulated. 
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VAX-1 1 BASIC recognizes five primary data types: integer, floating-point, character string, packed 
decimal, and RFA. These types correspond to the BASIC generic data-type keywords: 

• INTEGER 

• REAL 

• STRING 

• DECIMAL 

• RFA 

BASIC-PLUS-2 recognizes four primary data types: integer, floating-point, character string, and RFA. 
These types correspond to the BASIC generic data-type keywords: 

• INTEGER 

• REAL 

• STRING 

• RFA 

Integer data are stored as binary values in a byte, a word, or a longword. These values correspond to 
the BASIC data-type keywords: 

• BYTE 

• WORD 

• LONG 

Floating-point values are stored using a signed exponent and a binary fraction. VAX-1 1 BASIC allows 
four floating-point formats: single, double, gfloat, and hfloat. These formats correspond to the BASIC 
data-type keywords: 



• DOUBLE 

• GFLOAT 

• HFLOAT 

BASIC— PLUS— 2 allows only single and double floating-point formats. These formats correspond to the 
BASIC data-type keywords: 

• SINGLE 

• DOUBLE 

VAX-1 1 BASIC packed decimal data is stored in a string of bytes. Refer to Appendix C in BASIC on 
VAX/VMS Systems for more information on the storage of packed decimal data. 

Character data are strings of bytes containing ASCII codes as binary data. The first character in the 
string is stored in the first byte, the second character is stored in the second byte, and so on. VAX-1 1 
BASIC allows up to 65535 characters for a STRING data element. BASIC-PLUS-2 allows up to 32767 
characters. 

BASIC Reference Manual 11 



In addition to these data types, BASIC also recognizes a special RFA data type to provide information 
about a Record File Address (RFA). A Record File Address consists of a block number within a file and 
an offset into that block. An RFA uniquely identifies a record in a file. You can access RMS files of any 
organization by Record File Address (RFA). This means that you specify the disk address of a record, 
and RMS retrieves the record at that address. Accessing records by RFA is more efficient and faster 
than other forms of random record access. 

The RFA data type is unique and can be used only for: 

• RFA operations (with the GETRFA function and GET and FIND statements) 

• Assignments to other variables of the RFA data type 

• Comparisons with other variables of the RFA data type using the equal to ( = ) or not equal to (<>) 
relational operators 

• Formal and actual parameters 

• DEF and function results 

You cannot use variables or constants of the RFA data type for any arithmetic operations. You cannot 
declare a constant of the RFA data type. 

The RFA data type requires six bytes of information: four bytes for the address of a disk block, and 
two bytes for the offset into the disk block. See Chapter 9 in the BASIC User's Guide for more 
information on Record File Addresses and the RFA data type. 

Table 2 lists BASIC data-type keywords and summarizes BASIC data types. 
Table 2: BASIC Data Types 



Data Type 
Keyword* 


Size 


Range** 




Precision 

(decimal 

digits) 


INTEGER - specifies integer data 








BYTE 


8 bits 


-128 to +127 




NA 


WORD 


1 6 bits 


-32768 to +32767 




NA 


LONG 


32 bits 


-2147483648 to 
+2147483647 




NA 


REAL - specifies 


floating-point data 






SINGLE 


32 bits 


.29 * 1(T 38 to 1.7 * 


10 38 


6 


DOUBLE 


64 bits 


.29* 10" 38 to 1.7* 


10 38 


16 


CFLOAT 


64 bits 


.56 * 10' 30 " to .9 * 


w 30e 


15 


HFLOAT 


128 bits 


.84 * W 4932 to .59 


* io 4932 


33 


DECIMAL(d,s) 


to 16 bytes 


1 * 10~ 3 ' to 1 * 1(f 




31 


STRING 


One character 
per byte 


NA 




NA 


RFA 


6 bytes 


NA 




NA 



VAX-1 1 BASIC only data types are italicized. 
Approximate for REAL and DECIMAL data types. 
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For the VAX-1 1 BASIC only DECIMAL data type, you can specify the total number of digits (d) in the 

data type and the number of digits to the right of the decimal point (s). For instance, DECIMAL(10,3) <vax 

specifies decimal data with a total of 10 digits, 3 of which are to the right of the decimal point. 

In Table 2, REAL and INTEGER are generic data-type keywords that specify floating-point and integer 
storage, respectively, if you use the REAL or iNTEGER keywords to type data, the actual data type 
(SINGLE, DOUBLE, CFLOAT or HFLOAT in VAX-1 1 BASIC, BYTE, WORD, or LONG) depends 
on the current default. That is, if you do not explicitly type REAL and INTEGER data as SINGLE, 
DOUBLE, BYTE, WORD, and so on, BASIC uses the current defaults for REAL and INTEGER. 

You can specify data-type defaults in the BASIC environment with the SET and COMPILE commands 
or in a program module with the OPTION statement. On VAX/VMS systems, you can also specify 
data-type defaults from DCL level with the DCL BASIC command. You can also specify whether 
program values are to be typed implicitly or explicitly. The following sections discuss data-type 
defaults and implicit and explicit data typing. 

4.1 Implicit Data Typing 

You implicitly assign a data format to program values by adding a suffix to the variable name or 
constant value or by specifying no suffix with the variable name or constant value: 

• A dollar sign suffix ($) specifies STRING storage. 

• A percent sign suffix (%) specifies INTEGER storage. 

• No suffix character specifies storage of the default type, which may be INTEGER, REAL, or 
DECIMAL (VAX-1 1 BASIC only). 

Suffixes on variable names and program constants specify string, integer, or floating-point storage of 
the default size. No suffix character implies that the value is of the default type (integer, floating- 
point, or packed decimal in VAX-1 1 BASIC). With implicit data typing, the range and precision for 
integer, floating-point, and packed decimal values (VAX-1 1 BASIC only) is determined by the current 
default data type. The default data type is determined by the system default (REAL) or the data type set 
for the BASIC environment with the SET or COMPILE commands. VAX-1 1 BASIC qualifiers are 
described in Table 16. BASIC-PLUS-2 qualifiers are described in Table 17. 

Note that if you compile your program with the /TYPE: EXPLICIT qualifier, you cannot type program 
values implicitly. All program values must be explicitly assigned a data type in your program or 
BASIC signals an error. 

Good programming practice dictates that you do not mix implicit and explicit data typing in expres- 
sions or in program units and that you do not rely extensively on implicit data typing. Explicit data 
typing makes programs easier to understand and maintain because the data type of all program values 
is explicitly spelled out in the program and is not as dependent upon compilation defaults that may 
change. 

4.2 Explicit Data Typing 

Explicit data typing means that you use a declarative statement to specify the type, range and preci- 
sion of your program values. Declarative statements associate attributes such as data type and value 
with user identifiers. For example: 
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100 DECLARE STRING CONSTANT ZIP.CODE = 03060 

DECLARE STRING EMP.NAMEt DOUBLE WITH. TAX , SINGLE INT.RATE 

The first DECLARE statement associates the constant value 03060 and the STRING data type with a 
constant named ZIP_CODE. The second DECLARE statement associates the STRING data type with 
EMP-NAME, the DOUBLE data type with WITH_TAX, and the SINGLE data type with INT_RATE. 
No constant values are associated with user identifiers in the second DECLARE statement because 
they are variable names. 

With explicit data typing, each program variable within a program can have a different range and 
precision. This gives you more control over your program. Because you can explicitly assign data 
types to variables, constants, arrays, parameters, and functions, all integer data, for instance, does not 
have to take the compilation defaults. Likewise, all floating-point data does not have to take the 
compilation default because you can declare floating-point values as SINGLE or DOUBLE in 
BASIC-PLUS-2 and as SINGLE, DOUBLE, GFLOAT, or HFLOAT in VAX-/ / BASIC. See the BASIC 
User's Guide and the sections on these statements in this manual for more information on explicitly 
typing data. 

Using the REAL and INTEGER keywords to explicitly type program values allows you to write pro- 
grams that are transportable across systems, since these data-type keywords specify that all floating- 
point and integer data take the current default for REAL and INTEGER. The data type INTEGER, for 
example, specifies only that the constant or variable is an integer. The actual subtype (BYTE, WORD, 
or LONG) depends on the default set with the COMPILE or SET command, the VAX-1 1 BASIC DCL 
BASIC command, or the OPTION statement. 

You can also specify a particular data type size for values declared INTEGER or REAL with compila- 
tion qualifiers. The qualifier /DOUBLE, for instance, specifies that all data typed REAL is to be treated 
as double-precision data. 

The /TYPE: EXPLICIT qualifier or OPTION TYPE = EXPLICIT statement allows you to specify that all 
program data must be explicitly typed. Compiling a program with /TYPE: EXPLICIT or specifying 
OPTION TYPE = EXPLICIT means that any program value not explicitly declared causes BASIC to 
signal an error. 

For new applications, DIGITAL recommends using BASIC'S explicit data typing features. See Chapter 
5 of the BASIC User's Guide for more information. 

5.0. Constants 

A constant is a numeric or character literal that does not change during program execution. A 
constant can also be named and associated with a data type. BASIC allows the following types of 
constants: 

• Numeric 

Floating-point 

Integer 

Packed decimal (VAX-1 1 BASIC only) 

• String (ASCII characters enclosed in quotation marks) 

A constant of any of the above data types can be named with the DECLARE CONSTANT statement. 
You can then refer to the constant by name in your program. Refer to Section 5.3 for information on 
naming constants. 
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You can also use a special explicit literal notation to specify the value and data type of a numeric 
literal. Explicit literal notation is discussed in Section 5.4. 

If you do not specify a data type for a numeric constant with the DECLARE CONSTANT statement or 
with explicit literal notation, the type and size of the constant is determined by the default REAL, 
INTEGER, or (VAX-7 7 BASIC oniy) DECIMAL set: 

• At installation {BAS1C-PLUS-2 only) 

• With the DCL BASIC command (VAX- 7 7 BASIC only) 

• With the SET command 

• With the COMPILE command 

• With the OPTION statement 

BASIC also supplies predefined constants for ease in representing some ASCII characters and mathe- 
matical values. 

The following sections discuss numeric and string constants, named constants, explicit literal nota- 
tion, and predefined constants. 

5.1 Numeric Constants 

A numeric constant is a literal or named constant whose value never changes. In VAX-1 7 BASIC, a 
numeric constant can be a floating-point number, an integer, or a packed decimal number. In 
BASIC-PLUS-2 , a numeric constant can be either a floating-point number or an integer. The type and 
size of numeric constants are determined by the current default values, the data-type qualifiers 
specified with the COMPILE command, the defaults set by the SET command, the data type specified 
in a DECLARE CONSTANT or OPTION statement, or by explicit literal notation. 

If you use a declarative statement to declare data type and name a numeric constant, the constant is 
of the type and size specified in the statement. For example: 

100 DECLARE BYTE CONSTANT AGE = 12 

This example associates the numeric literal 12 and the BYTE data type with the user identifier AGE. 
To specify a data type for unnamed numeric constants, you must use the explicit literal notation 
format described in Section 5.4. 

5.1.1 Floating-Point Constants 

A floating-point constant is a literal or named constant with one or more decimal digits, either 
positive or negative, an optional decimal point and an optional exponent (E notation). If the default 
data type is INTEGER, a decimal point or an E is required or BASIC treats the literal as an INTEGER. In 
VAX-J 7 BASIC, if the default data type is DECIMAL, an E is required or VAX-7 7 BASIC treats the 
literal as a packed decimal value. The following, for example, are REAL literals: 

Default type REAL: 

-8.738 

239.21 E-6 

.79 

299 
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Default type INTEGER: 

-8.738 

239.21 E-6 

.79 

299E 

Default type DECIMAL (VAX-1 1 BASIC only): 

-8.738E 

239.21 E-6 

.79E 

299E 

Very large and very small numbers can be represented in E (exponential) notation. This form of 
mathematical shorthand uses the format: 

± number E ± n 

where: 

+ or- Is the number's sign. The plus sign is optional, but negative numbers require a minus 
sign. 

number Is the number carried to a maximum of: 

• 6 decimal places for SINGLE precision 

• 16 decimal places for DOUBLE precision 

• 15 decimal places for GFLOAT precision {VAX-1 1 BASIC only) 

• 33 decimal places for HFLOAT precision {VAX-1 1 BASIC only) 
E Represents the words "times 10 to the power of." 

+ or- Is the exponent's sign. The plus sign is optional, but the minus sign is mandatory for 
negative exponents. 

n Is an integer constant (the power of 10). If an exponent sign is specified, n can be zero, 

but not blank. If an exponent sign is not specified, n can be blank. 

Table 3 compares numbers in standard and E notation. 
Table 3: Numbers in E notation 



Standard Notation 


E Notation 


.0000001 

1,000,000 

-10,000,000 

100,000,000 

1,000,000,000,000 


.1E-06 
.1E + 07 
-.1E + 08 
.1E + 09 
.1E + 13 
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The range and precision of floating-point constants are determined by the current default data types or 
the explicit data type used in the DECLARE CONSTANT statement. There are, though, limits to the 
range allowed for numeric data types. Table 2 lists BASIC data types and ranges. BASIC signals the 
fatal error "floating point error or overflow" when your program specifies a constant value outside of 
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5.1.2 Integer Constants 

An integer constant is a literal or named constant, either positive or negative, with no fractional digits 
and an optional trailing percent sign (%). The percent sign is required for integer literals if the default 
type is not INTEGER. For example: 

Default type INTEGER: 

81257 

-3477 

79 

Default type REAL or (VAX-1 1 BASIC only) DECIMAL: 

81257% 

-3477% 

79% 

The range of allowable values for integer constants is determined by either the current default data 
type or the explicit data type used in the DECLARE CONSTANT statement. Table 2 lists BASIC data 
types and ranges. BASIC signals an error for a number outside the applicable range. 

BASIC treats numeric literals as floating-point numbers unless: 

• The default data type is INTEGER 

• The literal has a % suffix 

Thus, BASIC must convert numeric literals when assigning them to integer variables. This means that 
your program runs somewhat slower than it would if integer values were explicitly declared. You can 
prevent this conversion step by using percent signs for integer constants, numeric literal notation, or 
named integer constants. 

Note 

You cannot use percent signs in integer constants that appear in DATA statements. An 
attempt to do so causes BASIC to signal "Data format error" (ERR = 50). 



5.1.3 Packed Decimal Constants (VAX-1 1 BASIC Only) <vax 



A packed decimal constant is a number, either positive or negative, that has a specified number of 
digits and a specified decimal point position (scale). You specify the number of digits (d) and the 
position of the decimal point (s) when you declare the constant as a DECIMAL. If the constant is not 
declared, the number of digits and the position of the decimal are determined by the representation of 
the constant. For example, when the default data type is DECIMAL, 1.234 is a DECIMAL(4,3) con- 
stant, regardless of the default decimal size. Likewise, using explicit literal notation, "1.234"P is a 
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DECIMAL(4,3) constant, regardless of the default data type and default DECIMAL size. Explicit literal 
notation is described in Section 5.4. See the BASIC User's Guide for more information on packed 
decimal numbers. 

5.2 String Constants 

String constants are either string literals or named constants. A string literal is a series of characters 
enclosed in string delimiters. Valid string delimiters are: 

• Double quotation marks ("text") 

• Single quotation marks ('text') 

You can embed double quotation marks within single quotation marks ('this is a "text" string') and 
vice versa ("this is a 'text' string"). Note, however, that BASIC does not accept incorrectly paired 
quotation marks and that only the outer quotation marks must be paired. The following character 
strings, for example, are valid: 

"The record number does not exist." 

"I'm here!" 

"The terminating 'condition' is equal to A$." 

"REPORT 543" 

The following strings are not valid: 

"Quotation marks do not match' 

"No closing quotation mark 

Characters in string constants can be letters, numbers, spaces, tabs, or any ASCII character except a 
line terminator or NUL (ASCII code 0). If you need a string constant that contains a NUL, you should 
use the NUL predefined constant in a compile-time constant expression or explicit literal notation. 
See Section 5.4 in this manual for information on explicit literal notation and the BASIC User's Guide 
for more information on the NUL predefined constant. 

BASIC determines the value of the string constant by scanning all its characters. For example, because 
of the number of spaces between the delimiters and the characters, these two string constants are not 
the same: 

END-OF-FILE REACHED " 

"END-OF-FILE REACHED" 

BASIC stores every character between delimiters exactly as you type it into the source program, 
including: 

• Lowercase letters (a-z) 

• Leading, trailing, and embedded spaces 

• Tabs 

• Special characters 
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BASIC does not print the delimiting quotation marks when executing the program. That is, the value 
of the string constant does not include the delimiting quotation marks. For example: 



100 PRINT "END-OF-FILE REACHED' 



200 END 

RUNNH 

END-OF-FILE REACHED 



BASIC prints doubie or single quotation marks when they are enclosed in a second paired set: 

100 PRINT 'FAILURE CONDITION: "RECORD LENGTH"' 



200 END 

RUNNH 

FAILURE CONDITION: "RECORD LENGTH" 



5.3 Named Constants 

BASIC allows you to name constants. You can assign a mnemonic name to a constant that is internal 
to your program and refer to the constant by name throughout the program. You can also name a 
constant that is external to your program and refer to it by name throughout your program. This 
naming feature is useful for the following reasons: 

• If a commonly-used constant must be changed, you need to make only one change in your 
program. 

• A logically named constant makes your program easier to understand. 

You can use named constants anywhere you can use a constant, for example, to specify the number 
of elements in an array. 

You cannot change the value of an explicitly named constant during program execution. To change 
the value of a constant, you must change the program statement that names the constant and declares 
its value and then recompile the program. 

5.3.1 Naming Constants Within a Program Unit 

You name constants within a program unit with the DECLARE statement. For example: 

100 DECLARE DOUBLE CONSTANT P re f e r red _ rat e = ,147 

DECLARE SINGLE CONSTANT No rmal _ rate = .162 

DECLARE DOUBLE CONSTANT RisKv.rate = .175 
i 

500 New.bal = 01d_bal # (1 + P ref e r red _ rat e > "Yea rs _ payment 
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When interest rates change, only three lines have to be changed rather than every line that contains 
an interest rate constant. 

Constant names must conform to the rules for naming internal, explicitly declared variables listed in 
Section 6.1. No constant name can have embedded spaces. 

Tho \/ptuo accri^i^f-prl lA/ '^^ ^* n^rvy^A rrtnrt-» n f /-^« U« ~ *~ :l„ 4.: • _^ 11 i-. 1 

...^ .a,u>_ ^-^v-.nicu v.iui a nuiiiCu wwiuiaiii v-aii uc a njiiipiic-iime expression as weii as a literal 
value. For example: 

100 DECLARE STRING CONSTANT ConSrats = & 

" + + " + LF + CR + & 

"I Congratulations! ! " + CR + CR + & 

» + + " 



500 PRINT ConSrats 

I 
1000 PRINT ConSrats 

Named constants can save you programming time (since you don't have to retype the congratulations 
box every time you want to display it) and execution time (since the named constant is known at 
compile time). 

Allowable operators in DECLARE CONSTANT expressions include all valid arithmetic, relational, and 
logical operators except exponentiation. You cannot use built-in functions in DECLARE CONSTANT 
expressions. 

BASIC-PLUS-2 allows you to name floating-point, integer, and string constants, but floating-point 
constants cannot be named as expressions. Only STRING and INTEGER constants can be named as 
expressions in DECLARE CONSTANT statements. VAX-/ / BASIC allows constants of all data types to 
be named as expressions. For example: 

100 DECLARE DOUBLE CONSTANT £. 
MIN.VALUE = 0. & 
MAX.VALUE = PI /2 

This example is valid only in VAX- 7 7 BASIC. 

Note that you can specify only one data type in a DECLARE CONSTANT statement. To declare a 
constant of a different data type, you must use a second DECLARE CONSTANT statement. 

5.3.2 Naming Constants External to a Program Unit 

To declare constants outside the program unit, use the EXTERNAL statement. For example: 

200 EXTERNAL LONG CONSTANT SS*_ NORMAL 
EXTERNAL WORD CONSTANT IS.SUC 

The first line declares the VAX/VMS status code SS$_NORMAL to be an external LONG constant. 
The second line declares IS.SUC, a success code, to be an external WORD constant. Note that 
VAX-7 7 BASIC allows external BYTE, WORD, LONG, and SINGLE constants, while BASIC-PLUS-2 
allows only external WORD constants. The linker or task builder supplies the values for the constants 
specified in EXTERNAL statements. 
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External constant names cannot exceed six characters in BASIC-PLUS-2 and 31 characters in 
VAX-1 1 BASIC and must conform to the rules for naming external variables listed in Section 6.1 . No 
constant name can have embedded spaces. 

The types of external constants you can refer to vary from system to system. In VAX-1 1 BASIC, the 
named constant might be a system status code or a global constant declared in a VAX-1 1 MACRO or 
VAX-1 1 BLISS program. In BASIC— PLUS— 2, the named constant might be a global constant declared 
in a MACRO-1 1 program or an RMS constant. See the user's guide for your system for more informa- 
tion on external constants available to your programs. 

5.4 Explicit Literal Notation 

You can specify the value and data type of numeric literals by using a special notation. The format of 
this notation in VAX-1 1 BASIC is: 

[radix] num-str-lit [data-type] 

Radix specifies an optional base. 
In VAX-1 1 BASIC, radix can be: 

• D Decimal (base 10) 

• B Binary (base 2) 

• O Octal (base 8) 

• X Hexadecimal (base 1 6) 

The VAX-11 BASIC default radix is D, but you can also specify binary, octal, and hexadecimal 
integer literals. Binary, octal, and hexadecimal notation allows you to set or clear individual bits in 
the representation of an integer. This feature is useful in forming conditional expressions and in using 
logical operations. 

In BASIC-PLUS-2, num-str-lit is always treated as decimal (base 10), so the format for explicit literal 
notation in BASIC-PLUS-2 is: 

num-str-lit [data-type] 

Num-str-lit is a quoted string that can consist of digits and an optional decimal point when the radix is 
decimal. You can also use E notation for floating-point constants. A leading minus sign cannot appear 
inside the quotation marks, but can appear before the radix. 

In VAX-1 1 BASIC, num-str-lit can be the digits and 1 when the radix is binary, the digits through 7 
when the radix is octal, and the digits through F when the radix is hexadecimal. 

Data-type is an optional single letter that corresponds to a data-type keyword, excluding INTEGER 
and REAL: 

• B BYTE 

• W WORD 
• L LONG 

• F SINGLE 

(continued on next page) 
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• D DOUBLE 

• G GFLOAT (VAX-/ / BASIC only) 

• H HFLOAT (VAX-1 1 BASIC only) 

• P DECIMAL (VAX-1 1 BASIC only) 
For example: 

"255"L Specifies a LONG decimal constant with a value of 255. 

"4000"F Specifies a SINGLE decimal constant with a value of 4000. 

— "125"B Specifies a BYTE decimal constant with a value of -125. 

A quoted numeric string alone, without a radix and a data-type, is a string literal, not a numeric 
literal. For example: 

"255"W Specifies a WORD decimal constant with a value of 255. 

"255" Is a string literal. 

In VAX-1 1 BASIC, if you specify a binary, octal, or hexadecimal radix, data-type must be an integer. 
If you do not specify a data type, BASIC uses the default integer data type. For example: 

B"1 1 1 1 1 1 1 1 "B Specifies a BYTE binary constant with a value of -1 . 

B"1 1 1 1 1 1 1 1 "W Specifies a WORD binary constant with a value of 255. 

B"1 1111111" Specifies a binary constant of the default data type (BYTE, WORD, or LONG). 

B"1 1 1 1 1 1 1 1 "F Is illegal because F is not an integer data type. 

X"FF"B Specifies a BYTE hexadecimal constant with a value of -1 . 

X"FF"W Specifies a WORD hexadecimal constant with a value of 255. 

X"FF"D Is illegal because D is not an integer data type. 

0"377"B Specifies a BYTE octal constant with a value of -1 . 

0"377"W Specifies a WORD octal constant with a value of 255. 

0"377"G Is illegal because G is not an integer data type. 

When you specify a radix other than decimal, VAX-1 1 BASIC treats the numeric string as an unsigned 
integer. When, however, this value is assigned to a variable or used in an expression, VAX-1 1 BASIC 
treats the variable as a signed integer. For example: 

100 DECLARE BYTE A 

A = B"l 11111 11 "B 

PRINT A 
RUNNH 

-1 

In this example, VAX-1 1 BASIC sets all eight bits in storage location A. Because A is a BYTE integer, it 
has only 8 bits of storage and its value is -1 (the 8-bit two's complement of 1 is 1 1 1 1 1 1 1 1). If the 
data type were W (WORD), VAX-1 1 BASIC would set the bits to 000000001 1111111, and its value 
would be 255. 
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Note that in VAX— 7 1 BASIC a D can appear in both the radix position and the data type position. D in 
the radix position specifies that the numeric string is to be treated as a decimal number (base 10). D in 
the data type position specifies that the value is to be treated as a double-precision, floating-point 
constant. A P in the data type position specifies a packed decimal constant. For example: 

"255"D Specifies a double-precision constant with a value of 255. 

"255.55"P Specifies a DECIMAL constant with a value of 255.55. 

You can also use explicit literal notation to represent a single-character string in terms of its 8-bit 
ASCII value. The format in VAX-1 J BASIC is: 

[radix] num-str-lit C 

The format in BASIC-PLUS-2 is: 

num-str-lit C 

The letter C is an abbreviation for CHARACTER. The value of the numeric string must be between 
and 255, inclusive. 

This feature lets you create your own compi!e-time string constants containing nonprinting charac- 
ters. For example: 

100 DECLARE STRING CONSTANT CONTROL. G = "7"C 
PRINT C0NTR0L.G 

This example declares a string constant named CONTROI G (ASCII decimal value 7). When BASIC 

executes the PRINT statement, the terminal bell sounds. 

See the BASIC User's Guide for more information on explicit literal notation. 

5.5 Predefined Constants 

Predefined constants are symbolic representations of either: 1) ASCII characters or 2) mathematical 
values. They are also called compile-time constants because their value is known at compile time 
rather than at run time. Predefined constants: 

• Format program output to improve readability 

• Make source code easier to understand 

Table 4 lists predefined constants supplied by BASIC, their ASCII values, and their purposes. 
Table 4: Predefined Constants 




vVAX) 



Constant 


Decimal 
ASCII 
Value 


Purpose 


BEL (Bell) 

BS (Backspace) 

HT (Horizontal Tab) 


7 
8 
9 


Sounds the terminal bell 

Moves the cursor one position to the left 

Moves the cursor to the next horizontal tab stop 



(continued on next page) 
BASIC Reference Manual 23 



Table 4: Predefined Constants (Cont.) 





Decimal 




ASCII 


Constant 


Value 


LF (Line Feed) 


10 


VT (Vertical Tab) 


11 


FF (Form Feed) 


12 


CR (Carriage Return) 


13 


SO (Shift Out) 


14 


SI (Shift In) 


15 


ESC (Escape) 


27 


SP (Space) 


32 


DEL (Delete) 


127 


PI 


None 



Purpose 



Moves the cursor to the next line 

Moves the cursor to the next vertical tab stop 

Moves the cursor to the start of the next page 

Moves the cursor to the beginning of the current line 

Shifts out for communications networking, screen formatting, and alternate graphics 

Shifts in for communications networking, screen formatting, and alternate graphics 

Marks the beginning of an escape sequence 

Inserts one blank space in program output 

Deletes the last character entered 

Represents the number PI with the precision of the default floating-point data type 



You can use predefined constants in many ways. For example, to print and underline a word on a 
hard copy terminal: 



110 PRINT "NAME:" + BS + BS + BS + BS + BS + " 
120 END 

RUNNH 

NfiMF: 

To print and underline a word on a VT100 video display terminal: 

100 PRINT ESC + "r.4mNAME: " + ESC + "EOw" 
110 END 

RUNNH 

Note that the "m" in the above example must be lowercase. 

You can also create your own predefined constants with the DECLARE CONSTANT statement. For 
example: 



10 DECLARE STRING CONSTANT Unde rl ined _name 
20 DECLARE DOUBLE CONSTANT D.PI = PI 
30 PRINT Underlined.nawe 
PRINT D.PI . .PI 



ESC + "CilmNAME:" + ESC + "[0m" 



Line 10 defines Underlined_name as a string constant equivalent to the constant displayed by line 
100 in the previous example. Line 20 defines D_PI as a DOUBLE constant equal to the predefined 
constant PI. If the default REAL data size is SINGLE, the program can use both single-precision PI and 
double-precision D_PI. See the BASIC User's Guide for more information on predefined constants 
and their use in BASIC programs. 



24 



BASIC Reference Manual 



6.0 Variables 

A variable is a named quantity whose value can change during program execution. Each variable 
name refers to a location in the program's storage area. Each location can hold only one value at a 
time. Variables of all data types can have subscripts that indicate their position in an array. 

Depending on the program operations specified, the value of a variable can change from statement to 
statement. BASIC uses the most recently assigned value when performing calculations. This value 
remains until another statement assigns a new value to the variable. 

You can declare variables implicitly or explicitly. 

BASIC accepts these general types of variables: 

• Floating-point 

• Integer 

• String 

• RFA 

• Packed Decimal (VAX-1 1 BASIC only) 

• Record (VAX-1 1 BASIC only) 

See Chapter 9 in the BASIC User's Guide for more information on RFA variables and Chapter 6 in 
BASIC on VAX /VMS Systems for more information on record data structures. 

6.1 Variable Names 

The name given to a variable depends on whether the variable is internal or external to the program 
and whether the variable is implicitly or explicitly declared. 

1 . The name of an internal, explicitly declared variable must conform to the following rules: 

• The name consists of from 1 to 31 characters. 

• The first character of the name must be an upper- or lowercase alphabetic character (A 
through Z). 

• The last character of the name cannot be a dollar sign ($) or a percent sign (%). 

• The remaining characters, if present, can be any combination of upper- or lowercase letters 
(A through Z), numbers (0 through 9), dollar signs ($), underscores (_), or periods (.). The use 
of underscores in variable names helps improve readability and is preferred to the use of 
periods. 

2. The name of an internal, implicitly declared variable must conform to the following rules: 

• The name consists of from 1 to 31 characters. 

• The first character of the name must be an upper- or lowercase alphabetic character (A 
through Z). 

• The last character of the name can be either a dollar sign ($) to indicate a string variable or a 
percent sign (%) to indicate an integer variable. If the last character is neither a dollar sign 
nor a percent sign, the name indicates a variable of the default type. 
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• The remaining characters, if present, can be any combination of upper- or lowercase letters 
(A through Z), numbers (0 through 9), dollar signs ($), underscores (_), or periods (.). The use 
of underscores in variable names helps improve readability and is preferred to the use of 
periods. 

3. The name of an external, explicitly declared variable in VAX-1 1 BASIC must follow the rules 
for naming an internal, explicitly declared variable. 

4. The name of an external, explicitly declared variable in BASIC-PLUS-2 must conform to the 
following rules: 

• The name consists of from one to six characters. 

• The first character of the name must be an upper- or lowercase alphabetic character (A 
through Z). 

• The remaining characters, if present, can be any combination of upper- or lowercase letters 
(A through Z), numbers (0 through 9), dollar signs ($), or periods (.). 

5. A program cannot have external, implicitly declared variables since all implicitly declared 
names except SUB subprogram names are internal to the program. 

In all cases, no variable name can have embedded spaces. 

6.2 Implicitly Declared Variables 

BASIC accepts three types of implicitly declared variables: 

• Floating-point (or default data type) 

• Integer 

• String 

The name of an implicitly declared variable defines its data type. Integer variables end with a percent 
sign (%), string variables end with a dollar sign ($), and variables of the default type (usually floating- 
point) end with any allowable character except a percent sign or dollar sign. All three types of 
variables must conform to the rules listed in Section 6.1 for naming variables. The current data-type 
default (INTEGER, REAL, or, in VAX-7 1 BASIC, DECIMAL) determines the data type of implicitly 
declared variables that do not end in a percent sign (%) or dollar sign ($). 

A floating-point variable is a named location that stores a single floating-point value. The current 
default size for floating-point numbers (SINGLE, DOUBLE, or, in VAX-1 1 BASIC, GFLOAT or 
HFLOAT) determines the data type of the floating-point variable. The following are valid floating- 
point variable names: 

C L...5 ID_NUMBER 

M1 BIG47 STORAGE. LOCATION. FOR.XX 

F67T.J Z2. STRESS-VALUE 

If a numeric value of a different data type is assigned to a floating-point variable, BASIC converts the 
value to a floating-point number. 
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An integer variable is a named location that stores a single integer value. The current default size for 
integers (BYTE, WORD, or LONG) determines the data type of an integer variable. The following are 
valid integer variable names: 

ABCDEFG% C_8% RECORD. NUMBER% 

B% D6E7% THE.VALUE.i.WANT% 

If the default data type is INTEGER, the percent suffix (%) is not necessary. 

If you assign a floating-point or decimal {VAX-11 BASIC only) value to an integer variable, BASIC 
truncates the fractional portion of the value. It does not round to the nearest integer. For example: 

100 BX = -5,7 

BASIC assigns the value -5 to the integer variable, not -6. 

A string variable is a named location that stores strings. The following are valid string variable names: 



C1$ 


M$ 


EMPLOYEE_NAME$ 


L6$ 


F34G$ 


TARGET. RECORDS 


ABC1$ 


T..$ 


STORAGE_SHELF_IDENTIFIER$ 



Strings have both value and length. BASIC sets all string variables to a default length of zero before 
program execution begins, except those in a COMMON, MAP, or virtual array. See Sections 5.0 and 
35.0 in Part IV of this manual for information on string length in COMMON and MAP areas. See the 
BASIC User's Guide for information on default string length in virtual arrays. 

During execution, the length of a character string associated with a string variable can vary from zero 
(signifying a null or empty string) to 65535 characters in VAX-11 BASIC or 32767 characters in 
BASIC-PLUS-2. 

6.3 Explicitly Declared Variables 

In addition to implicitly declared variables described in the previous sections, BASIC lets you explic- 
itly assign a data type to a variable or an array. For example: 

100 DECLARE DOUBLE In t e rest _ rat e 

Data-type keywords are described in Section 4.0. For more information on explicit declaration of 
variables, see the sections on COMMON, DECLARE, DIMENSION, DEF, FUNCTION, EXTERNAL, 
MAP, and SUB in Part IV of this manual and Chapter 5 in the BASIC User's Guide. 

6.4 Subscripted Variables and Arrays 

A subscripted variable is part of an array. Arrays can be of any valid data type. Subscripted variables 
and arrays follow the same naming conventions as nonsubscripted variables. Subscripts follow the 
variable name in parentheses and define the variable's position in the array. When you create an 
array, bounds follow the array name in parentheses and define the maximum size of the array. For 
example: 

100 DECLARE STRING Emp _n ante ( 1000 ) 
200 FOR IX = 0% TO 1000% 

INPUT "Employee name " iEMF.name ( IX) 
NEXT IX 
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The DECLARE statement in the example on the previous page sets the bounds of array Emp_name to 
1000. Thus, the maximum value for an Emp_name subscript is 1000. The bounds of the array define 
the maximum value for a subscript of that array. 

In VAX-11 BASIC, subscripts can be any positive integer value from to 2147483646 in LONG 
mode. In BASIC-PLUS-2, subscripts can be any non-negative integer value from to 32766. 

Note 

The compiler signals an error if a subscript is bigger than the allowable range. Also, 
the amount of storage the system can allocate depends on available memory. There- 
fore, very large arrays may cause an internal allocation error. 

An array is a set of data ordered in any number of dimensions. A one-dimensional array, like 
Emp_name(1000), is called a list or vector. A two-dimensional array, like Payroll_data(5,5), is called 
a matrix. An array of more than two dimensions, like Big_array(1 5,9,2), is called a tensor. 

BASIC arrays are always zero-based. That is, the number of elements in any dimension always 
includes element number zero. For example, the array Emp_name(1000) contains 1001 elements, 
since BASIC allocates element zero. Payroll_data(5,5) contains 36 elements because BASIC always 
allocates row and column zero. 

For all arrays except virtual arrays, the total number of array elements cannot exceed 2147483647 
in VAX-11 BASIC and 32767 in BASIC-PLUS-2. For example, VAX-11 BASIC allows array 
A(2147483646) but does not allow array A(1 ,21 47483646). BASIC-PLUS-2 allows array A(32766) 
but does not allow array A(1, 32766). 

VAX-1 1 BASIC arrays can have up to 32 dimensions. BASIC-PLUS-2 arrays can have up to eight 
dimensions. You can also specify the type of data the array contains with data-type keywords. Table 2 
lists BASIC data types. 

An element in a one-dimensional array has a variable name followed by one subscript in parentheses. 
There can be a space between the array name and the parenthetical subscripts. For example: 

A(6%) 

B (6%) 

C$ (6%) 

A(6%) refers to the seventh item in this list: 

A(0%) A(1%) A(2%) A(3%) A(4%) A(5%) A(6%) 

An element in a two-dimensional array has two subscripts, in parentheses, following the variable 
name. The first subscript specifies the row number, the second specifies the column. Use a comma to 
separate the subscripts. There can be a space between the array name and the parenthetical sub- 
scripts. For example: 

A (7%, 2%) A%(4%,6%) A$(10%,10%) 
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In the following table, the arrow points to the element specified by the subscripted variable 

A%(4%,6%): 

COLUMNS 

12 3 4 5 6 

R0 00 00000 

01 0000000 

W2 0000000 

S3 0000000 

40 0000000^— A%(4%,6%) 

An element in an array has as many subscripts as there are dimensions. An element of 
Big_array(15%,9%,2%), for example, would have three subscripts. 

Although a program can contain a variable and an array with the same name, this is regarded as poor 
programming practice. Variable A and the array A(3%,3%) are separate entities and are stored in 
completely separate locations and should have different names. 

Note 

A program cannot contain two arrays with the same name and a different number of 
subscripts. For example, the arrays A(3%) and A(3%,3%) are invalid in the same 
program. 

BASIC arrays can be redimensioned at run time. See Chapter 7 in the BASIC User's Guide for more 
information on arrays. 

6.5 Initialization of Variables 

BASIC sets variables to zero or null values at the start of program execution. Variables initialized by 
BASIC include: 

• Numeric variables and in-storage array elements (except those in MAP or COMMON statements). 

• String variables (except those in MAP or COMMON statements). 

• Local variables in function definitions. In addition, BASIC sets these values to zero each time the 
program calls the function. 

• Variables in subprograms. Subprogram variables are initialized to zero or the null string each time 
the subprogram is called. 



BASIC does not initialize virtual arrays. 



Note 



In BASIC-PLUS-2 , variables in a MAP statement referenced in an OPEN statement are 
initialized to zero or the null string when the file is opened. In VAX-1 1 BASIC, these 
variables are not initialized. You can also use MACRO-1 1 routines to initialize MAP 
and COMMON areas. See BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E 
Systems for more information. 
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7.0 Expressions 

BASIC expressions consist of operands (numbers, strings, constants, variables, functions, or array 
elements) separated by: 

• Arithmetic operators 

• String operators 

• Relational operators 

• Logical operators 

All BASIC expressions except string concatenation and invocations of string-valued functions yield 
numeric values. The way you combine numeric operators and operands and use the resulting values 
allows you to produce: 

• Numeric expressions 

• String expressions 

• Conditional expressions 

BASIC evaluates expressions according to operator precedence and uses the results in program execu- 
tion. Parentheses can appear in expressions to group operands and operators, thus controlling the 
order of evaluation. 

The following sections explain the types of expressions you can create and the way BASIC evaluates 
expressions. 

7.1 Numeric Expressions 

Numeric expressions consist of floating-point, integer, or packed decimal (VAX-1 1 BASIC only) 
operands separated by arithmetic operators and optionally grouped by parentheses. Table 5 shows 
how numeric operators work in numeric expressions. 

Table 5: Arithmetic Operators 



Operator 


Example 


Use 


+ 


A + B 


Add B to A 


- 


A-B 


Subtract B from A 


* 


A* B 


Multiply A by B 


1 


A/B 


Divide A by B 


~ 


A"B 


Raise A to the power B 


** 


A**B 


Raise A to the power B 



In general, two arithmetic operators cannot occur consecutively in the same expression. Exceptions 
are the unary plus and unary minus. The following expressions are valid: 

A* + B 

A*-B 

A * (-B) 

A * + - + - B 
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The following expression is not valid: 

A - * B 
An operation on two numeric operands of the same data type yields a result of that type. For example: 

A% + B% yields an integer value of the default type. 

G3 * M5 yields a floating-point value if the default type is REAL. 

If the result of the operation exceeds the range of the data type, VAX-1 1 BASIC signals an overflow 
error message. For example: 

10 DECLARE BYTE At B 

A = 127 

B = 127 

PRINT A + B 
99 END 

This example causes VAX-1 1 BASIC to signal the error "Integer error or overflow" because the sum of 
A and B (254) exceeds the range of —1 28 to +127 for BYTE integers. Similar overflow errors occur for 
REAL and DECIMAL data types whenever the result of a numeric operation is outside the range of the 
data type. 

Assigning a value of one data type to a variable of a different data type changes the assigned value's 
data type to the variable's data type. For example: 

10 A% = 5.1 * S.3 

This example assigns the value 32 to the integer variable A% even though the floating-point value of 
the expression is 32.13. This is called numeric conversion. See Chapter 5 of the BASIC User's Guide 
for more information on numeric conversion. 

7.1.1 Floating-Point and Integer Promotion Rules 

When an expression contains operands with different data types, the data type of the result is deter- 
mined by BASIC'S data type promotion rules: 

• With one exception, BASIC promotes operands with different data types to the lowest common data 
type that can hold the largest or most precise possible value of either operand's data type, then 
performs the operation in that data type, and yields a result of that data type. 

• The exception to the previous rule is that when an operation involves SINGLE and LONG data 
types, BASIC promotes the LONG data type to SINGLE, rather than to DOUBLE, performs the 
operation, and yields a result of the SINGLE data type. 

Note that BASIC does a sign extend when converting BYTE and WORD integers to a higher INTEGER 
data type (WORD or LONG). That is, the high order bit (the sign bit) determines how the additional 
bits are set when the BYTE or WORD is converted to WORD or LONG. If the high order bit is zero 
(positive), all higher-order bits in the converted BYTE or WORD are set to zero. If the high order bit is 
one (negative), all higher-order bits in the converted BYTE or WORD are set to one. 

Table 6 lists the data type results possible in numeric expressions that combine BYTE, WORD, 
LONG, SINGLE, and DOUBLE data. Table 7 lists the data type results possible in numeric expres- 
sions that combine the VAX-1 1 BASIC only data types, GFLOAT and HFLOAT. Note that in VAX-1 1 
BASIC, when the operands are DOUBLE and GFLOAT, BASIC promotes both values to HFLOAT, and 
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returns an HFLOAT value. The promotion of DOUBLE and GFLOAT to HFLOAT is necessary because 
a DOUBLE value is more precise than a GFLOAT value, but cannot contain the largest possible 
GFLOAT value. Consequently, BASIC promotes these data types to a data type that can hold the 
largest and most precise value of either operand. 

Table 6: Result Data Types in BASIC Expressions 









Operand 2 






Operand 1 


BYTE 


WORD 


LONG 


SINGLE 


DOUBLE 


BYTE 


BYTE 


WORD 


LONG 


SINGLE 


DOUBLE 


WORD 


WORD 


WORD 


LONG 


SINGLE 


DOUBLE 


LONG 


LONG 


LONG 


LONG 


SINGLE 


DOUBLE 


SINGLE 


SINGLE 


SINGLE 


SINGLE 


SINGLE 


DOUBLE 


DOUBLE 


DOUBLE 


DOUBLE 


DOUBLE 


DOUBLE 


DOUBLE 



vax> Table 7: VAX-11 BASIC Result Data Types 





Operand 2 


Operand 1 


GFLOAT 


HFLOAT 


BYTE 


GFLOAT 


HFLOAT 


WORD 


GFLOAT 


HFLOAT 


LONG 


GFLOAT 


HFLOAT 


SINGLE 


GFLOAT 


HFLOAT 


DOUBLE 


HFLOAT 


HFLOAT 


GFLOAT 


GFLOAT 


HFLOAT 


HFLOAT 


HFLOAT 


HFLOAT 



As Table 6 shows, if one operand is SINGLE and one operand is DOUBLE, BASIC promotes the 
SINGLE value to DOUBLE, performs the specified operation, and returns the result as a DOUBLE 
value. This promotion is necessary because the SINGLE data type has less precision than the 
DOUBLE value, whereas the DOUBLE data type can represent all possible SINGLE values. If BASIC 
did not promote the SINGLE value and the operation yielded a result outside of the SINGLE range, 
loss of precision and significance would occur. 

The data types BYTE, WORD, LONG, SINGLE, and DOUBLE form a simple hierarchy: if all operands 
in an expression are these data types, the result of the expression is the highest data type used in the 
expression. 



vax> 7.1.2 DECIMAL Promotion Rules (VAX-11 BASIC only) 



VAX-1 1 BASIC also allows the DECIMAL(d,s) data type. The number of digits (d) and the scale or 
position of the decimal point (s) in the result of operations involving a DECIMAL value depends on the 
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data type of the other operand. If one operand is DECIMAL and the other is DECIMAL or INTEGER, 
the d and s values of the result are determined as follows: 

• If both operands are typed DECIMAL, and if both operands have the same digit (d) and scale (s) 






If r*f fk/-» nnrtnti^n k~ 



~tlw tkf 



>!< 



VdlUCS, i liJ *_UI I vci 3iwi id uv-V-ui ai Ji-i uic ic3un ui li ic w|_/ci anui i i icij caoa-u y li iC jainc v_i anu d voiuvj uj 

the operands. Note, however, that overflow can occur if the result exceeds the range specified by 
the d value. 



If both operands are DECIMAL but have different digit and scale values, BASIC always uses the 
larger number of specified digits for the result. 

For example: 

100 DECLARE DECIMALS, 2) A 
DECLARE DECIMAL(4t3) B 

Variable A allows three digits to the left of the decimal point and two digits to the right. Variable B 
allows one digit to the left of the decimal point and three digits to the right. Therefore, the result 
allows three digits to the left of the decimal point and three digits to the right: 

A 

B 



Result 



• If one operand is typed DECIMAL and one is typed INTEGER, the INTEGER value is converted to a 
DECIMAL(d,s) data type as follows: 

BYTE is converted to DECIMAL(3,0). 

WORD is converted to DECIMAL(5,0). 

LONG is converted to DECIMAL(10,0). 

BASIC then determines the d and s values of the result by evaluating the d and s values of the 
operands as described above. 

Note that only INTEGER data types are converted to the DECIMAL data type. If one operand is 
DECIMAL and one is floating-point, the DECIMAL value is converted to a floating-point value. The 
total number of digits (d) in the DECIMAL value determines its new data type, as shown in Table 8. 

Table 8: Result Data Types for DECIMAL Data 



Number of 

DECIMAL Digits 

in Operand 


SINGLE 


Floating-point Operanc 
DOUBLE GFLOAT 


s 
HFLOAT 


1-6 


SINGLE 


DOUBLE 


GFLOAT 


HFLOAT 


7-15 


DOUBLE 


DOUBLE 


GFLOAT 


HFLOAT 


16 


DOUBLE 


DOUBLE 


HFLOAT 


HFLOAT 


17-31 


H FLOAT 


HFLOAT 


HFLOAT 


HFLOAT 
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If the value of d is between 7 and 1 5, the operand is converted to: 

• DOUBLE if the floating-point operand is SINGLE or DOUBLE 

• GFLOAT if the floating-point operand is GFLOAT 

• HFLOAT if the floating-point operand is HFLOAT 

Thus, a DECIMAL(8,5) operand is converted to DOUBLE if the other operand is SINGLE or DOUBLE, 
to GFLOAT if the other operand is GFLOAT, and to HFLOAT if the other operand is HFLOAT. 

Note aiso that exponentiation of a DECIMAL data type returns a REAL value. 

See the BASIC User's Guide for more information on data type interactions, conversions, and promo- 
tion rules in BASIC numeric expressions. 

7.2 String Expressions 

String expressions are string entities separated by the plus sign ( + ). When used in a string expression, 
the plus sign concatenates strings. 

For example: 

100 INPUT "Type two words to be comb ined" ; A* » B* 

C* = A* + B* 

PRINT C* 
200 END 

RUNNH 

Type two words to be combined? hello 
? soodbye 

hel losoodbye 
Ready 

7.3 Conditional Expressions 

Conditional expressions can be either relational or logical expressions. 

Numeric relational expressions compare numeric operands to determine whether the expression is 
true or false. String relational expressions compare string operands to determine which string expres- 
sion occurs first in the ASCII collating sequence. 

Logical expressions contain integer operands and logical operators. BASIC determines whether the 
specified logical expression is true or false by testing the numeric result of the expression. Note that in 
conditional expressions, as in any numeric expression, when BYTE and WORD operands are con- 
verted to WORD and LONG, the specified operation is performed in the higher data type, and the 
result returned is also of the higher data type. When one of the operands is a negative value, this 
conversion will produce accurate but perhaps confusing results, because BASIC performs a sign 
extend when converting BYTE and WORD integers to a higher integer data type. See Section 7.1 .1 for 
information on integer conversion rules. 
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7.3.1 Numeric Relational Expressions 

Operators in numeric relational expressions compare the values of two operands and return: 1) a 
minus one if the relation is true or 2) a zero if the relation is false. The data type of the result is the 
default integer type. For example: 

Example 1 

100 A = 10 

B = 15 

XX = (A <> B> 
IF XX = -1% 

THEN PRINT 'Relationship is true' 
ELSE IF XX = 

THEN PRINT 'Relationship is false' 

END IF 
END IF 



RUNNH 



Relationship is true 
Example 2 

10 A = 10 
B = 15 
XX = A = B 
IF XX = -IX 

THEN PRINT 'Relationship is true' 
ELSE IF XX = 

THEN PRINT 'Relationship is false' 

END IF 
END IF 



RUNNH 

Relationship is false 

Table 9 shows how numeric operators work in numeric relational expressions. 
Table 9: Numeric Relational Operators 



Operator 


Example 


Meaning 


= 


A = B 


A is equal to B. 


< 


A< B 


A is less than B. 


> 


A> B 


A is greater than B. 


<= or =< 


A<= B 


A is less than or equal to B. 


>= or => 


A >= B 


A is greater than or equal to B. 


<> or >< 


A<> B 


A is not equal to B. 


= = 


A == B 


A and B will PRINT the same because 
they are equal to six significant digits. 
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7.3.2 String Relational Expressions 

Operators in string relational expressions determine how BASIC compares strings. BASIC determines 
the value of each character in the string by converting it to its ASCM value. ASCII values are listed in 
Appendix C in BASIC on VAX/VMS Systems, BASIC on RSX-1 1 M/M-PLUS Systems, and BASIC on 
RSTS/E Systems. BASIC compares the strings character by character, left to right, until it finds a 
difference in ASCII value. For example: 

10 A* = 'ABC 

B* = 'ABZ' 

20 IF A$ < B* 

THEN PRINT 'ABC comes before ABZ' 

GOTO 99 
ELSE IF A* == B* 

THEN PRINT 'The strinSs are identical' 

GOTO 99 
ELSE IF A* > B$ 

THEN PRINT 'ABC comes after ABZ' 

GOTO 99 
END IF 
END IF 
END IF 
55 PRINT 'StrinSs are equal but not identical' 
99 END 

In this example, BASIC compares A$ and B$ character by character. The strings are identical up to 
the third character. Because the ASCII value of "Z" (90) is greater than the ASCII value of "C" (67), 
A$ is less than B$. BASIC evaluates the expression A$ < B$ as true (-1), prints "ABC comes before 
ABZ" and goes to line 99. 

If two strings of differing lengths are identical up to the last character in the shorter string, BASIC pads 
the shorter string with spaces (ASCII value 32) to generate strings of equal length, unless the operator 
is the double equals sign (= =). If the operator is the double equals sign, BASIC does not pad the 
shorter string. For example: 

10 A$ = 'ABCDE' 

B* = 'ABC 
20 PRINT 'B$ comes before A$' IF B$ < A* 
PRINT 'A$ comes before B$ ' IF A* < B* 
30 C$ = 'ABC ' 
IF B* == C* 

THEN PRINT 'B* exactly matches C$' 
ELSE PRINT 'B$ does not exactly match C$ ' 
END IF 
IF B$ = C* 

THEN PRINT 'B$ matches C$ with padding' 
ELSE PRINT 'B* does not match C$ ' 
END IF 

RUNNH 

B* comes before A* 

B* does not exactly match C$ 

B$ matches C$ with padding 

In this program, BASIC compares "ABCDE" to "ABC " to determine which string comes first in the 
collating sequence. "ABC " comes before "ABCDE" because the ASCII value for space (32) is lower 
than the ASCII value of "D" (68). Then BASIC compares "ABC " with "ABC" using the double 
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equals sign and determines that the strings do not match exactly without padding. The third compari- 
son uses the single equals sign. BASIC pads "ABC" with spaces and determines that the two strings 
match with padding. 

Table 10 shows how numeric operators work in string relational expressions. 
Table 10: String Relational Operators 



Operator 


Example 


Meaning 


< 
> 

<= or =< 
>= or => 
<> or >< 


A$ = B$ 

A$ < B$ 
A$> B$ 
A$ < = B$ 
A$ >= B$ 
A$ <> B$ 
A$ = = B$ 


Strings A$ and B$ are identical after the shorter string has been padded with spaces to 
equal the length of the longer string. 

String A$ occurs before string B$ in ASCII sequence. 

String A$ occurs after string B$ in ASCII sequence. 

String A$ is identical to or precedes string B$ in ASCII sequence. 

String A$ is identical to or follows string B$ in ASCII sequence. 

String A$ is not identical to string B$. 

Strings A$ and B$ are identical in composition and length, without padding. 



BASIC treats unquoted strings typed in response to the INPUT statement differently than quoted strings 
by ignoring leading and trailing spaces and tabs. That is, BASIC evaluates the quoted strings "ABC" 
and "ABC " as equal but not identical because the = = operator does not pad the shorter string 
with spaces. When you input the same strings as unquoted strings in response to the INPUT prompt, 
BASIC evaluates them as equal and identical because it ignores the trailing spaces. The LINPUT 
statement, on the other hand, treats unquoted strings as string literals so the trailing spaces are part of 
the string, and BASIC evaluates the strings as equal but not identical. 

7.3.3 Logical Expressions 

A logical expression contains either: 

• A unary iogicai operator and one integer operand 

• Two integer operands separated by a binary logical operator 

• One integer operand 

Logical expressions are valid only when the operands are integers. If the expression contains two 
integer operands of differing data types, the resulting integer has the same data type as the higher 
integer operand. For instance, the result of an expression that contains a BYTE integer and a WORD 
integer would be a WORD integer. Table 6 shows how integer data types interact with each other in 
expressions. 

BASIC determines whether the condition is true or false by testing the result of the logical expression 
to see whether any bits are set. If no bits are set, the value of the expression is zero and it is evaluated 
as false; if any bits are set, the value of the expression is nonzero, and the expression is evaluated as 
true. BASIC generally accepts any nonzero value in logical expressions as true. However, logical 
operators can return unanticipated results unless minus one is specified for true values and zero for 
false. Therefore, logical operators should be used on the results of relational expressions to obtain 
valid and predictable results. Table 11 lists logical operators. Examples that show how logical opera- 
tors work on nonzero and minus one values follow the table. 
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Table 1 1 : Logical Operators 



Operator 



Example 



NOT 


NOT A% 


AND 


A% AND B% 


OR 


A% OR B% 


XOR 


A% XOR B% 


EQV 


A% EQV B% 


IMP 


A% IMP B% 



Meaning 



The bit-by-bit complement of A%. If A% is true (-1), NOT A% is false (0). 

The logical product of A% and B%. A% AND B% is true only if both A% and B% are true. 

The logical sum of A% and B%. A% OR B% is false only if both A% and B% are false; 
otherwise, A% OR B% is true. 

The logical exclusive OR of A% and B%. A% XOR B% is true if either A% or B% is true 
but not if both are true. 

The logical equivalence of A% and B%. A% EQV B% is true if A% and B% are both true 
or both false; otherwise, the value is false. 

The logical implication of A% and B%. A% IMP B% is false only if A% is true and B% is 
false; otherwise, the value is true. 



The truth tables in Table 12 summarize the results of these logical operations. Zero is false; minus one 
is true. 

Table 12: Truth Tables 



A% 




NOTA% 


A% 


B% 


A% OR B% 







-1 











-1 










-1 


-1 








-1 


-0 


-1 








-1 


-1 


-1 


A% 


B% 


A% AND B% 


A% 


B% 


A% EQV B% 

















-1 





-1 








-1 





-1 








-1 








-1 


-1 


-1 


-1 


-1 


-1 


A% 


B% 


A% XOR B% 


A% 


B% 


A% IMP B% 

















-1 





-1 


-1 





-1 


-1 


-1 





-1 


-1 








-1 


-1 





-1 


-1 


-1 



The operators XOR and EQV are logical complements. 

Note that in logical expressions, any nonzero value is evaluated as true, while in relational expres- 
sions, a minus one is generated as a true value. Logical operators set bits in the result of the expres- 
sion; any bit set is a nonzero value and is evaluated as true. For this reason, it is important to use 
logical operators on the results of relational expressions (the values of minus one and zero) to avoid 
unanticipated results. For example: 

10 A% = 2% 
20 BZ = 1X1 
30 IF AX THEN PRINT 'A% IS TRUE' 
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40 IF B% THEN PRINT 'BX IS TRUE' 

50 IF AX AND BX THEN PRINT 'AX AND BX IS TRUE' 

ELSE PRINT 'AX AND BX IS FALSE' 
60 END 



AX IS TRUE 
BX IS TRUE 
AX AND BX IS FALSE 

In this example, the values of A% and B% both test as true because they are nonzero values. 
However, the logical AND of these two variables returns an unanticipated result of "false." 

The program returns this seemingly contradictory result because logical operators work on the indi- 
vidual bits of the operands. The 8-bit binary representation of 2% is: 

1 

The 8-bit binary representation of 4% is: 

1 

Each value tests as true because it is nonzero. However, the AND operation on these two values sets 
a bit in the result only if the corresponding bit is set in both operands. Therefore, the result of the 
AND operation on 4% and 2% is: 

00000000 

No bits are set in the result, so the value tests as false (zero). 

If the value of B% is changed to 6%, the resulting value tests as true (nonzero) because both 6% and 
2% have the second bit set. Therefore, BASIC sets the second bit in the result and the value tests as 
nonzero and true. 

The 8— bit binary representation of minus one is: 



The result of -1 % AND -1 % is -1 % because BASIC sets bits in the result for each corresponding bit 
that is set in the operands. The result, therefore, tests as true because it is a nonzero value. For 
example: 

10 AX = -IX 

20 BX = -IX 

30 IF AX THEN PRINT 'AX IS TRUE' 

40 IF BX THEN PRINT 'BX IS TRUE' 

50 IF AX AND BX THEN PRINT 'AX AND BX IS TRUE' 

ELSE PRINT 'AX AND BX IS FALSE' 

B0 END 

RUNNH 

AX IS TRUE 
BX IS TRUE 
AX AND BX IS TRUE 
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Your program may also return unanticipated results if you use the NOT operator with a nonzero 
operand that is not minus one. For example: 



10 


AX=-1X 






20 


BX = 2 






30 


IF AX THEN PRINT 'AX 


IS TRUE' 






ELSE PRINT 'AX 


IS FALSE' 




40 


IF BX THEN PRINT 'BX 


IS TRUE' 






ELSE PRINT 'BX 


IS FALSE' 




50 


IF NOT AX THEN PRINT 


'NOT AX IS 


TRUE' 




ELSE PRINT 


'NOT AX IS 


FALSE 


B0 


IF NOT BX THEN PRINT 


'NOT BX IS 


TRUE' 




ELSE PRINT 


'NOT BX IS 


FALSE 


99 


END 







RUNNH 



A% IS TRUE 
BX IS TRUE 
NOT AX IS FALSE 
NOT BX IS TRUE 



In this example, BASIC evaluates both A% and B% as true because they are nonzero. NOT A% is 
evaluated as false (zero) because the binary complement of minus one is zero. NOT B% is evaluated 
as true because the binary complement of two has bits set and, therefore, is a nonzero value. 

Note 

DIGITAL recommends that you use logical operators on the results of relational 
expressions to avoid obtaining unanticipated results. 

7.4 Evaluating Expressions 

BASIC evaluates expressions according to operator precedence. Each arithmetic, relational, and string 
operator in an expression has a position in the hierarchy of operators. The operator's position tells 
BASIC when to perform the operation. Parentheses can change the order of precedence. 

Table 13 lists all operators as BASIC evaluates them. Note that: 

• Operators with equal precedence are evaluated logically from left-to-right. 

• BASIC evaluates expressions enclosed in parentheses first, even when the operator in parentheses 
has a lower precedence than that outside the parentheses. 
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Table 1 3: Numeric Operator Precedence 



**or* 


Highest 


- (unary minus) or + (unary plus) 






* or / 






+ or- 






+ (concatenation) 






all relational operators 






NOT 






AND 






OR, XOR 






IMP 


< 


' 


EQV 


Lowest 



BASIC thus evaluates the expression A = 15*2 + 12*2 - (35 * 8) in five steps: 



1. 15*2 = 225 

2. 12*2 = 144 

3. 225 + 144 = 369 

4. (35 * 8) = 280 

5. 369 - 280 = 89 



Exponentiation (left-most expression) 

Exponentiation 

Addition 

Multiplication 

Subtraction 



There is one exception to this order of precedence: when an operator that does not require operands 
on either side of it (such as NOT) immediately follows an operator that does require operands on both 
sides (such as +), BASIC evaluates the second operator first. For example: 

A% + NOT B% + C% 

This expression is evaluated as: 
(A% + (NOT B%)) + C% 

BASIC evaluates the expression NOT B before it evaluates the expression A + NOT B. When the 
NOT expression does not follow the + expression, the normal order of precedence is followed: 

NOT A% + B% + C% 

This expression is evaluated as: 
NOT ((A% + B%) + C %) 



BASIC Reference Manual 41 



BASIC evaluates the two plus expressions (A% + B%) and ((A% + B%) + C%) because the plus ( + ) 
operator has a higher precedence than the NOT operator. 

BASIC evaluates nested parenthetical expressions from the inside out. For example: 

100 A = < ( ( <25 + 5) / 5) * 7) + 3) 

OO T KIT A 

nuiii n 

300 B = 25 + 5/5*7 + 3 

PRINT B 

RUNNH 

35 
35 

In this program, BASIC evaluates the parenthetical expression A quite differently from expression B. 
For expression A, BASIC evaluates the innermost parenthetical expression (25 + 5) first, then the 
second inner expression (30 / 5), then (6 * 7), and finally (42 + 3). For expression B, BASIC evaluates 
(5 / 5) first, then (1 * 7), then (25 + 7 + 3) to obtain a different value. 
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PART II 

wCiMpsssr 

Commands 



APPEND 



1.0 APPEND 



Function 



The APPEND command merges an existing BASIC source program with the program currently in 
memory. 

Format 



APPEND [ file-spec l 



Syntax Rules 

1. File-spec names the file of BASIC program lines you want to merge with the program 
currently in memory. The VAX-1 1 BASIC default file type is BAS, and the BASIC-PLUS-2 
default file type is B2S. 

General Rules 

1 . If you type APPEND without specifying a file name, BASIC prompts with: 
Append file nanie-- 

Respond with a file name. If you respond with a carriage return and no file name, VAX-1 1 
BASIC searches for a file named NONAME.BAS. BASIC-PLUS-2 searches for a file named 
NONAME.B2S. If the compiler cannot find NONAME.BAS or NONAME.B2S, VAX-1 1 
BASIC signals the error "file not found"; BASIC-PLUS-2 signals "can't find file or 
account". 
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2. You can append the contents of file-spec to a source program called into memory with the 
OLD command or created in the BASIC environment. If there is no program in memory, 
BASIC appends the file-spec to an empty program with the default file name, NONAME. 

3. If the file-spec contains a BASIC line with the same line number as a line of the program in 
memory, the line in the appended file replaces the line of the program in memory. Other- 
wise, BASIC inserts appended lines into the program in memory in sequential, ascending 
line number order. 

4. The APPEND command does not change the name of the program in memory. 

5. If you have not saved the appended version of the program, BASIC signals the warning 
"Unsaved change has been made, CTRL/Z or EXIT to exit" the first time you try to leave 
the BASIC environment. 

Examples 

APPEND PROGB 
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9 ft ASSIftN fVAX-11 basics 

Function 

The ASSIGN command equates a logical name to a complete file specification, a device, or another 
logical name within the context of the BASIC environment. 

Format 



ASSIGN equiv-nam[:] log-nam[:] 



Syntax Rules 



1 . Equiv-nam specifies the file specification, device, or logical name to be assigned a logical 
name. If you specify a physical device name, terminate it with a colon (:). 

2. Log-nam is the 1- to 63-character logical name to be associated with equiv-nam. You can 
specify a logical name for any portion of a file specification. If the logical name translates 
to a device name, and will be used in place of a device name in a file specification, 
terminate it with a colon (:). 

General Rules 

1 . When the logical name assignment supersedes another logical name assigned previously, 
BASIC displays the message "previous logical name assignment replaced". 

2. If log-nam has more than 63 characters, BASIC signals the error "invalid logical name". 

3. Logical names assigned with the ASSIGN command are placed in the process logical name 
table and remain there until you exit the BASIC environment. 

Examples 

ASSIGN [LEONARD, BAS] PRO: 
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3.0 BRLRES (BASIC-PLUS-2) 

Function 

The BRLRES command allows you to specify a memory-resident BASIC-PLUS-2 or user-created 
library to be used when you task-build the program. When you use the BUILD command, 
BASIC-PLUS-2 includes the specified library in the Task Builder command file. The default library for 
the BRLRES command is chosen by your system manager when BASIC-PLUS-2 is installed. 

Format 



BRLRES [ lib-param ] 



lib-param: 



file-spec 
NONE 



Syntax Rules 



1 . If you enter the BRLRES command without a lib-param, BASIC prompts for one and dis- 
plays the name of the current default memory-resident library. 

• File-spec can be a library supplied by BASIC-PLUS-2 or a user-created library. 

• NONE tells the Task Builder not to link your task to the BASIC-PLUS-2 default resident 
library. Therefore, the Task Builder links to the BASIC-PLUS-2 object module library, 
BP20TS.OLB. 

• If you type a carriage return in response to the prompt, the current default memory- 
resident library is used. 

General Rules 

1. The memory-resident libraries supplied by BASIC-PLUS-2 are LB:[1,1]BP2RES and 
LB:[1,1]BP2SML on RSX-11M/M-PLUS systems and LB:BP2RES and LB:BP2SML on 
RSTS/E systems. LB: is a RSTS/E logical name for the library account on disk. Because 
memory-resident libraries are optional, your system manager can select none, one, or both 
when BASIC-PLUS-2 is installed. See BASIC on RSX-1 1M/M-PLUS Systems or BASIC on 
RSTS/E Systems for information on BASIC-PLUS-2 memory-resident libraries. 

2. BASIC-PLUS-2 links the specified memory-resident library to your program when you 
task-build the program, so you must use the BRLRES command before you use the BUILD 
command to include the specified library in the Task Builder command file. 

3. The BRLRES library you specify is included in your Task Builder command files until you 
specify a new library with the BRLRES command or exit from the BASIC environment. 
When you exit from the environment, the original default library is restored as the default. 

4. You can override the BRLRES command with the /BRLRES qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD operation. 
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5. The Task Builder returns an error message when the requested memory-resident library is 
not available. 

6. Consult your system manager for information about the resident libraries available to you. 

Examples 

RSX-1 1M/M-PLUS Systems 

BRLRES LBsCi .UBP2RES 
QCTC/F Cwctomc 
BRLRES LBsBP2RES 
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4.0 BUILD (BASIC-PLUS-2) 

Function 

The BUILD command generates a command (CMD) file and an overlay description language (ODL) 
file for the Task Builder. The command file contains instructions that enable the Task Builder to link 
your program module(s) with libraries and other routines. The overlay description language file 
specifies how segments of the task-built program are overlaid when you run it. 

Format 



BUILD [ prog-nam [ sub-nam,... ] ] [ /qualifier 



Syntax Rules 

1. Prog-nam names the program you want to build. If you do not specify a prog-nam, 
BASIC-PLUS-2 creates CMD and ODL files for the current program or for NONAME if 
there is no current program. 

2. Sub-nam names the subprogram or subprograms you want to link to the main program. 
You must specify a prog-nam if you specify a sub-nam. 

3. The command file takes the name of the main program and a default extension of CMD. 
The ODL file takes the name of the main program and a default extension of ODL. 

4. /Qualifier specifies a qualifier keyword that sets a BASIC default. Table 17 lists all 
BASIC-PLUS-2 qualifiers and describes their functions. 

5. The BUILD command line must fit on a single 80-character line. 
General Rules 

1. The BUILD command does not change the current context of the BASIC-PLUS-2 
environment. 

2. The BUILD command generates the CMD and ODL files. It does not cause the Task Builder 
to begin operation. 

3. In addition to program names and build qualifiers, the BUILD command accepts defaults 
from previously specified BRLRES, DSKLIB, ODLRMS, RMSRES, LIBR, and SET commands. 

4. BUILD qualifiers tell the Task Builder to perform special operations on object modules 
when you task-build the program. You can abbreviate all qualifiers to the first three letters 
of the qualifier keyword. 

Examples 

BUILD MAIN>SUBi f SUB2 / DUMP / REL 
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5.0 $ Command 

Function 

You can enter a system command while in the BASIC environment by typing a dollar sign ($) before 
the command. BASIC passes the command to the operating system for execution. The context of the 
BASIC environment and the program currently in memory do not change in VAX-1 1 BASIC and 
BASIC-PLUS-2 on RSX-1 1M/M-PLUS systems. On RSTS/E systems, the system command executes 
and control returns to the default run-time system, not to BASIC— PLUS— 2. 

Format 



$ system-command 




Syntax Rules 

1. BASIC passes system-command directly to your operating system without checking for 
validity. 

General Rules 

1 . The terminal displays any error messages or output that the system-command generates. 

VAX-? 1 BASIC <vax) 

1 . Control returns to the BASIC environment after the system-command executes. The context 
(source file status, loaded modules, and so on) of the BASIC environment and the program 
currently in memory do not change unless the system-command causes the operating 
system to abort BASIC or log you out. 

2. On VAX/VMS systems, the system-command you specify executes within the context of a 
subprocess. Consequently, commands such as the DCL SET command execute only within 
the subprocess and do not affect the process running BASIC. 

BASIC-PLUS-2 

1. On RSX-1 IM/M-PLUS systems, control returns to the BASIC environment after the 
system-command executes. The context (source file status, loaded modules, and so on) of 
the BASIC environment and the program currently in memory do not change unless the 
system-command causes the operating system to abort BASIC or log you out. 

2. On RSTS/E systems, the context of the environment and the program currently in memory Trstsj 
are lost. After the system command executes, control passes to monitor level, not to — 
BASIC-PLUS-2. 

3. If you have made changes to the program currently in memory, BASIC— PLUS-2 displays 
the message "Unsaved change has been made - type SCRATCH or REPLACE" when you 
enter a system-command. 
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$ Command 



Examples 

VAX-1 1 BASIC 

Ready 

$SHDW PROTECTION 

SYSTEM = RWED» 0WNER=RWED» GROUP = RWED , WORLD = RE 

Ready 
BASIC-PLUS-2 

*DIR STOCK. B2S 

XUnsaved chansfe has been made - type SCRATCH or REPLACE. 

BASICZ 

REPLACE 

BASIC2 

SDIR ST0CK.B2S 
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6.0 COMPILE 



Function 



The COMPILE command converts a BASIC source program to an object module and writes the object 
file to disk. 

Format 



COMPILE [ file-spec ] [ /qualifier ]... 



Syntax Rules 



1 . File-spec specifies a name for the output file or files. If you do not provide a file-spec, the 
compiler uses the name of the program currently in memory for the file name, a default file 
type of OBJ for the object file, and a default file type of LIS (VAX-11 BASIC) or LST 
{BASIC-PLUS-2) for the listing file, if a listing file is requested. BASIC-PLUS-2 uses a 
default file type of MAC for the macro source code file when a macro file is requested. 

2. In VAX-/ 1 BASIC, file-spec can precede or follow /qualifier. In BASIC-PLUS-2, file-spec 
must precede the qualifiers. 

3. /Qualifier specifies a qualifier keyword that sets a BASIC default. See Section 22.0 for 
information on BASIC qualifiers. Table 16 lists and describes VAX-11 BASIC qualifiers. 
Table 17 lists and describes BASIC-PLUS-2 qualifiers. 

4. In cases of ambiguous or erroneous qualifiers, VAX-11 BASIC signals "Unknown quali- 
fier", BASIC-PLUS-2 signals "Illegal switch", and the program does not compile. When 
qualifiers conflict, BASIC compiles the program using the last specified conflicting quali- 
fier. For example: 

COMPILE/ OBJ /N00BJ 

BASIC compiles the program currently in memory but does not create an OBJ file. 

5. You can abbreviate all positive COMPILE qualifiers to the first three letters of the qualifier 
keyword. A negative qualifier can be abbreviated to NO and the first three letters of the 
qualifier keyword. 

6. There must be a program in memory or the COMPILE command does not execute and 
BASIC does not signal an error or warning. 



General Rules 



If an object file for the program already exists in your directory, BASIC-PLUS-2 on RSTS/E 
systems overwrites it with the new object file. VAX-1 1 BASIC and BASIC-PLUS-2 on 
RSX-1 1M/M-PLUS systems create a new version of the OBJ file. 
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2. You should not specify both a file name and file type. For example: 

COMPILE NEWOBJ.FIL/LIS/OBJ 

v*x> • VAX-/ 7 BASIC creates two versions of NEWOBJ.FIL. The first version, NEWOBJ.FIL;1 , is 

th e listing file; the second version, NEWOBJ.FIL;2, is the object file. If you specify only a 
file name, BASIC uses the OBJ and LIS file type defaults when creating these files. 

• BASIC-PLUS-2 creates only the object file and names it NEWOBJ.FIL. 

3. Use the COMPILE /NOOBJECT command to check your program for errors without pro- 
ducing an object file. 

Examples 

COMPILE NEWSTRING/DOUBLE/LIST 
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Function 



The CONTINUE command continues program execution after BASIC executes a STOP statement or, 
in VAX-/ 7 BASIC, encounters a CTRL/C. 

Format 



CONTINUE 




Syntax Rules 

None. 

General Rules 

1. In VAX-? 7 BASIC, a program stops executing in response to a STOP statement or a <(yAx) 
CTRL/C: 

• You can enter immediate mode commands and resume program execution with the 
CONTINUE command. 

• You cannot resume program execution if you have made source code changes or 
additions. 

2. In BASIC-PLUS-2, a program stops executing when BASIC executes a STOP statement and (BP2J 
control passes to the BASIC-PLUS-2 debugger, which prompts with a pound sign (#). ^-^ 
Type the CONTINUE command to resume program execution. Note that if the program 

was executed with the RUN /DEBUG command, you can enter debugger commands be- 
fore resuming program execution with the CONTINUE command. See Part VI in this 
manual for more information on debugger commands. 

Examples 

VAX- 7 7 BASIC 

XBAS-I-STO » Stop 

-BAS-I-FROLINMOD > from line 25 in module ABC 

Ready 

CONTINUE 

BASIC-PLUS-2 

Stop at line 20 
•CONTINUE 
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8.0 DELETE 

Function 

The DELETE command removes a specified line or range of lines from the program currently in 
memory. 

Format 




Syntax Rules 



1 . You must enter at least one line number. If you do not, DELETE has no effect in VAX-1 1 
BASIC, while BASIC-PLUS-2 signals the error "Illegal Delete command". 

2. The sep characters allow you to delete individual lines or a block of lines. 

• If you separate line numbers with commas, BASIC deletes each specified line number. 

• If you separate line numbers with a hyphen (-), BASIC deletes the inclusive range of 
lines. The lower line number must come first. If it does not, DELETE has no effect in 
VAX-1 I BASIC, while BASIC-PLUS-2 signals the error "Bad line number pair". 

3. You can combine individual line numbers and line ranges in a single DELETE command. 
Note, however, that a line number range must be followed by a comma and not another 
hyphen, or BASIC signals an error. 



General Rules 

1 . BASIC-PLUS-2 signals an error if there are no lines in the specified range. VAX-1 1 BASIC 
does not signal an error and the DELETE command has no effect. 

2. If you do not specify a beginning line number for a range, VAX-1 1 BASIC signals the error 
"illegal line number". BASIC-PLUS-2 assumes a beginning line number of 1 and deletes 
all lines in the range 1 - lin-num. 

3. If you do not specify an end line number in a range, VAX-1 1 BASIC does not delete any 
lines and does not signal an error. BASIC-PLUS-2 deletes only the specified line number. 

Examples 

DELETE 50 

DELETE 70-BO. 110, 124 

DELETE 50»60t90-110 
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9,0 DSKLIB (BASIC-PLUS-2) 



Function 



The DSKLIB command lets you select a disk-resident, object module library to be used when you 
build your program. When you use the BUILD command, BASIC-PLUS— 2 includes the specified 
library in the Task Builder command file. Every system has a disk library default set when 
BASIC-PLUS-2 is installed. 

Format 



DSKLIB [ file-spec ] 



Syntax Rules 



1 . If you enter the DSKLIB command without a file-spec, BASIC-PLUS-2 prompts for one and 
displays the name of the current default disk-resident library. 

• File-spec can be a disk-resident, object module library supplied with BASIC— PLUS— 2 or a 
user-created library. 

• If you type a carriage return in response to the prompt, BASIC— PLUS— 2 uses the default 
disk-resident library. 



General Rules 



1. The object module libraries supplied by BASIC-PLUS-2 are LB:BP20TS.OLB on RSTS/E 
systems and LB:[1,1]BP20TS.OLB on RSX-1 IM/M-PLUS systems. LB: is a RSTS/E logical 
name for the library account on disk. These libraries contain the BASIC Object Time 
System (OTS). OLB is the default object module library file type. If your system does not 
have memory-resident libraries, the Task Builder extracts all BASIC routines from these 
disk-resident libraries. See BASIC on RSX-1 1M/M-PLUS Systems and BASIC on RSTS/E 
Systems for more information on object module libraries. 

2. The Task Builder links the specified library to your program when you task-build the 
program. You must use the DSKLIB command before you use the BUILD command to 
include the library you want in the Task Builder command file. 

3. The DSKLIB library you specify is included in all Task Builder command files until you 
specify a new library with the DSKLIB command or exit from the BASIC environment. 
When you exit from the BASIC environment, the default object module library set at 
installation is restored as the default disk-resident library. 

4. You can override the DSKLIB command with the /DSKLIB qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD routine. 

5. The Task Builder returns an error message when the requested disk-resident library is not 
available. 

6. Consult your system manager for information about the disk-resident libraries available to 
you. 
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Examples 

RSX-1 1M/M-PLUS Systems 

DSKLIB LB:C1 »1]BP20TS 
RSTS/E Systems 

DSKLIB LB:BP2DTS 
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10.0 EDIT 



Function 



The EDIT command allows you to edit individual program lines in the BASIC environment. In 
VAX-1 1 BASIC, EDIT with no arguments invokes the default text editor and reads the current program 
into the editor's buffer. In BASIC-PLUS-2 , EDIT with no arguments puts you in the BASIC-PLUS-2 
editing mode. BASIC-PLUS-2 editing mode commands are listed in Table 14 and described in 
Sections 10.1 to 10.6. 

Format 



VAX- 


-11 BASIC 










EDIT [ [ lin-num 


] search-clause [ replace-clause ] ] 








search-clause: 
replace-clause: 


delim unq-str1 delim 

[ unq-str2 ] [ delim [ int-const1 


] [ 


int-const2 ] ] 



BASIC-PLUS-2 




vax; 



EDIT [ [ lin-num [ - lin-num ] ] search-clause [ replace-clause ] ] 



search-clause: delim unq-str1 delim 
replace-clause: [ unq-str2 ] delim [ int-const1 ] 



Syntax Rules 

1 . Lin-num specifies the line to be edited. 

2. Search-clause specifies the text you want to remove or replace. Unq-strl is the search 
string you want to remove or replace. 

3. Replace-clause specifies the replacement text and the occurrence of the search string you 
want to replace. 

• Unq-str2 is the replacement string. 

• Int-constl specifies the occurrence of unq-strl you want to replace. If you do not specify 
an occurrence, BASIC replaces the first occurrence of unq-strl . 

4. Delim can be any printing character not used in unq-strl or unq-str2. The examples in this 
and the following sections use the slash (/) as a delimiter. 

5. The delim characters in search-clause must match, or BASIC signals an error. 

6. If the delim you use to signal the end of replace-clause does not match the delim used in 
search-clause, BASIC does not signal an error and treats the end delim as part of unq-str2. 
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7. BASIC replaces or removes text in a program line as follows: 

• If unq-strl is found, BASIC replaces it with unq-str2. 

• If unq-strl is not found, BASIC signals an error. 

• If unq-strl is null, VAX-1 1 BASIC signals "no change made". BASIC-PLUS-2 replaces 
the first character of the last edited line with unq-str2 and does not signal an error. 

• If unq-str2 is null, BASIC deletes unq-strl. The delim in the replace-clause is required if 
you want to delete unq-str 1 . 

• BASIC matches and replaces strings exactly as you type them. If unq-strl is uppercase, 
BASIC searches for an uppercase string. If it is lowercase, BASIC searches for a lowercase 
string. 



vax> VAX- J 7 BASIC 



The EDIT command followed by a carriage return causes BASIC to temporarily save your 
program in a file called BASEDITMP.TMP. BASIC then invokes the same editor you use 
when you type the DCL EDIT command. When you finish editing your program and 
exit the editor, the edited program is the program currently in memory, and the context 
of the BASIC environment is unchanged. Note that BASIC deletes all versions of 
BASEDITMP.TMP when you return to BASIC from the editor. 

lnt-const2 in replace-clause specifies the sub-line of a block of program code where you 
want BASIC to begin the search. 



BP2) BASIC-PLUS-2 



1. The EDIT command followed by a carriage return puts you in the BASIC-PLUS-2 editing 
mode. Editing mode commands, listed in Table 14 and described in Sections 10.1 to 10.6, 
are valid only in the BASIC-PLUS-2 editing mode. The editing mode prompt is an asterisk 

(*). 

2. BASIC-PLUS-2 sets a specified line number as the current edit line, even when the editing 
operation fails. That line number remains set as the current edit line until you specify 
another line number or exit the BASIC environment. 

3. You can edit a range of lines by separating two line numbers with a hyphen. BASIC signals 
an error and does not edit the specified range if there are spaces between the hyphen and 
the line numbers. 

4. If you specify a range of lines and an occurrence, BASIC replaces each occurrence of 
unq-strl in each line of the range beginning with the specified occurrence. For example: 

10 PRINT DISPLAY*, DISPLAY** DISPLAY* 
20 PRINT DISPLAY** DISPLAY** DISPLAY* 
EDIT 10-20 /DISPLAY*/NEW*/2 

10 PRINT DISPLAY** NEW** NEW* 
20 PRINT DISPLAY*, NEW*, NEW* 

"DISPLAY*" replaced bv "NEW*". 
4 substitutions 
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General Rules 

VAX-1 1 BASIC Owx; 

1 . VAX-1 1 BASIC displays the edited line with changes after the EDIT command successfully 
executes. 

2. If you specify a lin-num with no text parameters, VAX-1 1 BASIC displays the line. 
BASIC-PLUS-2 ( BP2 ) 

1 . BASIC-PLUS-2 displays the edited line or lines with changes after the EDIT command 
successfully executes. It also displays a message showing the search string, replacement 
string, and number of replacements made. 

2. If you want to edit a range of numbers, you must specify both the beginning and end of the 
range. BASIC-PLUS-2 does not default to the last edited line or to the last line number in 
the program. 

3. When you specify a lin-num with no text parameters, BASIC-PLUS-2 displays the message 
"Current edit line is x", where x is the specified lin-num. 

4. When you type EDIT with no parameters to enter the editing mode, BASIC-PLUS-2 checks 
the last edited line number to make sure that it still exists in the current program. If it has 
been deleted, BASIC-PLUS-2 displays the message "?No current line". 

Examples 

VAX-1 1 BASIC 

EDIT 100 /LEFT*/RIGHT*/3»2 
EDIT 

BASIC-PLUS-2 

EDIT 300-400 /LEFT$/ / 
EDIT 300 /LEFT*/RIGHT$/3 
EDIT 
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BP2) Table 14: BASIC-PLUS-2 Editing Mode Commands 



Command 



Function 



DEFINE 



EXECUTE 

EXIT (or CTRL /Z) 

FIND 

INSERT 

SUBSTITUTE 



Used to enter a macro definition. A macro definition consists of editing commands. You cannot, 
though, use the DEFINE and EXECUTE commands in a macro definition. To end the macro 
definition, type a carriage return and then EXIT or CTRL/Z. You must use the EXECUTE command 
to execute the macro definition. 

Executes the macro defined by the DEFINE command as many times as you specify. 

Allows you to exit from editing mode, execute an INSERT command, or end a DEFINE command. 

Searches from the last edited line to the end of the current program for a specified string. 

Allows you to add program lines after a specified line number. Type a carriage return and EXIT or 
CTRL/Z to execute this subcommand. 

Performs the same function and accepts the same text parameters as the EDIT command; you 
cannot, however, specify line numbers or line number ranges. 
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10.1 DEFINE (BASIC-PLUS-2) 

Function 

The DEFINE editing mode command allows you to enter a macro definition. The macro consists of a 
series of editing mode commands in the order in which they are to execute. 

Format 




Syntax Rules 



1. The macro definition must consist of valid editing mode commands or BASIC— PLUS— 2 
signals an error. You cannot use the DEFINE or EXECUTE editing mode commands in a 
macro definition. 



General Rules 

1 . Type the DEFINE command and a carriage return, then enter your macro definition. Type 
EXIT or CTRL/Z in response to the DEFINE prompt (->) when you have finished entering 
your macro definition. BASIC— PLUS— 2 displays the editing mode prompt, and you can 
enter more editing commands. 

2. BASIC writes the macro definition to a file, so the definition remains in effect until you 
enter another DEFINE command. That is, an EXECUTE command executes the last defined 
macro definition. 

Examples 

*DEFINE 

Enter command sequence: 
->FIND REM 

-SUBSTITUTE /REM/ ! / 
->EXIT 
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10.2 EXECUTE (BASIC-PLUS-2) 

Function 

The EXECUTE editing mode command executes the last macro defined by the DEFINE command. You 
specify the number of times the macro is to execute. 

Format 




Syntax Rules 



1 . Int-const specifies the number of times the macro executes. If you do not specify int-const, 
BASIC— PLUS— 2 executes the macro once. 



General Rules 



1. An EXECUTE command always executes the last defined macro definition. If no macro 
definition exists, BASIC-PLUS-2 signals the error "Command sequence has not been 
defined". 



Examples 

♦EXECUTE 5 
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10.3 EXIT or CTRL/Z (BASIC-PLUS-2) 

Function 

The EXIT or CTRL/Z editing mode command marks the end of a DEFINE or INSERT command or exits 
from editing mode. 

Format 




Syntax Rules 

None. 

General Rules 



1 . If you type EXIT or CTRL/Z in response to the editing mode prompt, BASIC-PLUS-2 exits 
from editing mode. 

2. If you type EXIT or CTRL/Z to end a DEFINE or INSERT command, BASIC-PLUS-2 dis- 
plays the editing mode prompt and you can enter more editing commands. 



Examples 

♦DEFINE 

Enter command sequence 
->FIND REM 

"*jri_?i_rLri_r / 111.11 f ; 

->EXIT 
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10.4 FIND (BASIC-PLUS-2) 

Function 

The FIND editing mode command searches the current program for a specified string starting at the 
last edited line and continuing to the end of the program. 

Format 




Syntax Rules 



1. The FIND command does not require character delimiters for unq-str. Delimiters are the 
space after the command and a carriage return. 

General Rules 

1 . When unq-str is found, BASIC-PLUS-2 displays the line that contains the unq-str, sets it as 
the last edited line, and displays an informational message. 

2. If unq-str is not found, the last edited line remains unchanged and BASIC-PLUS-2 displays 
a message telling you that the string was not found. 

3. The FIND command matches unq-str exactly as you type it. If unq-str is uppercase, 
BASIC-PLUS-2 searches for uppercase characters. The delimiters (space and carriage 
return) are not included in the match. 

4. If you do not specify an unq-str, the FIND command matches the unq-str specified by the 
last FIND command. If there is no previous FIND command, BASIC-PLUS-2 matches the 
first character of the last edited line. 

Examples 

*FIND PRIMT 

330 PRIMT 'How many receipts do you have ' jRECEIPTS 

"PRIMT" found on line 330 
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10.5 INSERT (BASIC-PLUS-2) 

Function 

The INSERT editing mode command allows you to add lines to a program. 

Format 




Syntax Rules 



1 . Lin-num specifies the line number after which you want to insert new program lines. If you 
do not specify a lin-num, BASIC defaults to the last edited line. 

2. If lin-num does not exist in the source program currently in memory, BASIC signals an 
error. 



General Rules 

1 . Type in program lines, beginning with a line number, after entering the INSERT command. 
When you are finished inserting lines, type EXIT or CTRL/Z to return to the editing mode. 
BASIC-PLUS-2 displays the editing mode prompt and you can enter more editing 
mode commands. 

2. If you insert a line number that already exists, BASIC— PLUS— 2 replaces the existing line 
with the code you insert and does not signal a warning. 

3. BASIC-PLUS-2 does not perform syntax checks on inserted program lines even when 
syntax checking is enabled. 

4. The current edit line does not change. For example, if the current edit line is 10 and you 
insert lines 20 and 30, line 10 remains the current edit line. 

Examples 

♦INSERT 30 

Enter lines to be added after line 30 
->40 INPUT 'More receipts ' JRECEI PTS* 
->50 IF RECEIPTS* = "" 
-> THEN GOTO 32767 
-> END IF 
->EXIT 
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10.6 SUBSTITUTE (BASIC-PLUS-2) 
Function 



The SUBSTITUTE editing mode command allows you to substitute one character string for another in 
the program currently in memory. SUBSTITUTE is the editing mode equivalent of the EDIT command 
with one exception: you cannot specify a range of lines. The SUBSTITUTE subcommand can replace 
only one occurrence of the specified search string, while the EDIT command can replace all occur- 
rences in a range of lines, if you so specify. 



Format 



S 

SUBSTITUTE ) search-clause [ replace-clause ] 



search-clause: delim unq-str1 delim 

replace-clause: [ unq-str2 ] delim [ int-const ] 



Syntax Rules 



1 . Delim marks the beginning and end of the search and replace strings. Delimiters are 
required before and after unq-strl. The delimiter after unq-str2 is optional. 

• Delim can be any printing character not used in the search or replace strings. The 
examples in this section use the slash (/) as a delimiter. 

• The beginning and ending delim characters must match, or BASIC signals an error. 

2. Unq-strl specifies the string you want to remove or replace. Unq-str2 specifies the string to 
be substituted for unq-strl. 

• If unq-strl is found, BASIC replaces it with unq-str2. 

• If unq-strl is not found, BASIC signals an error. 

• If you do not specify unq-str2, BASIC deletes unq-strl. 

• If you do not specify unq-strl, BASIC replaces the first character of the last edited line 
with unq-str2. 

• The SUBSTITUTE subcommand matches and replaces strings exactly as you type them. If 
unq-strl is uppercase, BASIC searches for an uppercase string. If it is lowercase, BASIC 
searches for a lowercase string. 

3. Int-const specifies the occurrence of str-litl you want to replace. If you do not specify an 
int-const, BASIC replaces the first occurrence of str-litl. 

4. If you type only the SUBSTITUTE subcommand and a carriage return, BASIC-PLUS-2 
signals the error "Parameters required". 
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Qgngraj Riijoc 

1 . BASIC displays the edited line with changes after the SUBSTITUTE command executes. 
Examples 

♦SUBSTITUTE /AS / ABSOLUTES / 3 
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11.0 EXIT 

Function 

The EXIT command or CTRL/Z clears memory and returns control to the operating system. 
Format 



EXIT 



Syntax Rules 

None. 

General Rules 

1 



If you type EXIT after creating a new program or editing an old program without first typing 
SAVE or REPLACE, BASIC signals "Unsaved change has been made, CTRL/Z or EXIT to 
exit". The message warns you that the new or revised program will be lost if you do not 
SAVE or REPLACE it. If you type EXIT again, BASIC exits from the environment whether 
you have saved your changes or not. 



Examples 

EXIT 
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12.0 HELP 



Function 



The HELP command displays on-line documentation for BASIC commands, keywords, statements, 
functions, and conventions. 

Format 



HELP [ unq-str ] ... 



Syntax Rules 

1 . If you type HELP with no parameters, BASIC displays a list of topics. 

2. Unq-str is BASIC topic, keyword, command, statement, function, or convention. 

3. The first unq-str must be a topic. If it is not, BASIC displays a list of topics for you to choose 
from. 

4. You can specify a subtopic after the topic. Separate one unq-str from another with a space. 

5. You can use the asterisk (*) wildcard character in unq-str or alone as unq-str. If you use an 
asterisk in unq-str, BASIC displays information on all topics that match the specified por- 
tion of unq-str. If you use the asterisk alone, BASIC displays information on all BASIC 
topics. 

General Rules 

1 . If the unq-str you specify is not a unique topic or subtopic, BASIC displays a information on 
all topics or subtopics beginning with unq-str. For example: 

Ready 

HELP STATEMENTS CH 

STATEMENTS 

CHAIN 

The CHAIN statement transfers control from the current p roSram to another 
BASIC prosram, The prosram to which you CHAIN must be in executable 
f o rmat . 

Fo rmat 

CHAIN <str-exp> 

Example 

240 CHAIN "COSINE, EXE" 

(continued on next page) 
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STATEMENTS 
CHANGE 

The CHANGE statement: 1) converts a string- of characters to their ASCII 
integer ualuest or 2) converts a list of numbers to a strins of ASCII 
characte rs < 

Format 

Strins Variable to Array: 

CHANGE str-exp TO num-array 
Array to Strins Variable: 

CHANGE num-array TO str-vbl 
Exampl e 

200 CHANGE ARRAY-CHANGES TO A* 
Topic? 

2. An asterisk (*) indicates that you want to display information that matches any portion of 
the topic you specify. For example, if you type HELP GO*, BASIC displays information on 
GOSUB and GOTO. 

3. When information on a particular topic or subtopic is not available, BASIC signals the 
message "Sorry, no documentation on unq-str" and a list of "Additional information 
available". 

Examples 

HELP STATEMENTS ON GOTO 
STATEMENTS 
ON 

GOTO 

The ON GOTO statement transfers proSram control to one of several lines ( 
depending on the value of a control expression. 

Format 

■C GO TO > 
ON int-exp < GOTO } tarSet >.., I OTHERWISE tarSet 3 

Exampl e 

330 ON INDEX* GOTO 700 ,800 ,900 , OTHERWISE 1000 
Topic? 
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13.0 IDENTIFY 



Function 



The IDENTIFY command displays an identification header on the controlling terminal. The header 
contains the name and version number of BASIC. 

Format 



IDENTIFY 



General Rules 



1 . The message displayed by the IDENTIFY command includes the name of the BASIC com- 
piler and the version number. 



Examples 

VAX-1 1 BASIC 

IDENTIFY 

VAX-11 BASIC V2.0 

BASIC-PLUS-2 

IDENTIFY 

PDP-11 BASIC-PLUS-2 V2.0 
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14.0 INQUIRE 

Function 

The INQUIRE command is a synonym for the HELP command. See the HELP command for syntax 
rules. 
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15.0 LIBRARY (BASIC-PLUS-2) 

Function 

The LIBRARY command allows you to specify a memory-resident BASIC-PLUS-2 or user-created 
library to be used when you task-build the program. When you use the BUILD command, 
BASIC-PLUS-2 includes the specified library in the Task Builder command file. The default library for 
the LIBRARY command is chosen by your system manager when BASIC-PLUS-2 is installed. 

Format 



LIBRARY [ lib-param ] 



lib-param: { file-spec 
lib-nam 
NONE 



Syntax Rules 

1 . If you enter the LIBRARY command without a lib-param, BASIC-PLUS-2 prompts for one and 
displays the name of the current default memory-resident library. 

• Lib-nam or file-spec can be a memory-resident library supplied by BASIC-PLUS-2 or a user- 
created library. If you specify only lib-nam with no device, BASIC-PLUS-2 assumes LB: on 
RSTS/E systems and LB:[1,1] on RSX-1 1 M I M-PLUS systems. 

• NONE tells the Task Builder not to link your task to the BASIC default memory-resident 
library. Therefore, the Task Builder links to the BASIC disk-resident, object module 
library, BP20TS.OLB. 

• If you type a carriage return in response to the prompt, the current default memory-resident 
library is used. 

General Rules 

1. The memory-resident libraries supplied by BASIC-PLUS-2 are BP2RES and BP2SML. 
Because memory-resident libraries are optional, your system manager can select none, 
one, or both then BASIC-PLUS-2 is installed. See BASIC on RSX-1 1MIMPLUS Systems or 
6A5/C on RSTS/E Systems for information on using BASIC-PLUS-2 memory-resident librar- 
ies. See your system manager for information on the libraries available on your system. 

2. On RSTS/E systems, the LIBRARY command does not require the LB: logical name. BASIC 
automatically searches this account for the memory-resident library symbol table. On 
RSX-1 1M/ M-PLUS systems, the LIBRARY command automatically references libraries on 
LB: [1,1] unless you specify another UIC. 

3. BASIC-PLUS-2 links the specified library to your program when you task-build the pro- 
gram. You must use the LIBRARY command before you use the BUILD command to 
include the specified library in the Task Builder command file. 
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4. The library you specify is included in your Task Builder command files until you specify a 
new library with the LIBRARY command or exit from the compiler. When you exit from the 

COmpilpr. the oriejnal default lihrarv ic roetruroA ckc tUa rW-j.ilt 

5. You can override the LIBRARY command with the /LIBRARY qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD routine. 

6. The Task Builder returns an error message when the requested resident library is not 
available. 

Examples 

LIBRARY BP2RES 
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16.0 LIST and LISTNH 

Function 

The LIST command displays the program lines of the program currently in memory. Line numbers are 
sequenced in ascending order. LISTNH displays program lines without the program header. 

Format 

VAX-77 BASIC 



( LISlNH 
j LIST 


[ lin-num [ sep [lin-num ]]]... 


sep: 


i 




BASIC-PLUS-2 




LISTNH J 

LIST J [ [ - ] lin-num ] [ sep [ lin-num ] ]... 


sep: l - 






CVAX) 



Syntax Rules 



1. The LIST command displays program lines, along with a header containing the program 

name, uic i_umcek unic, dnu uic uaic. i \j sup|jic» uic piOgiaui i icauci , lypc lioiiNm. 

2. LIST without parameters displays the entire program. 

3. The sep characters allow you to display single lines or a range of lines. 

• To display single lines, separate line numbers with commas. For example: 
LIST 30»70 

displays a header and lines 30 and 70. 

• To display an inclusive range of lines, separate line numbers with a hyphen. The first 
number must be lower than the second number in the range or BASIC signals an error. 
For example: 

LIST 30-70 

displays lines 30 through 70. 

4. Line number ranges must be separated from other ranges or individual line numbers by 
commas as BASIC does not allow two consecutive hyphens. 
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vax> VAX-1 1 BASIC 




1. A hn-num loliowed by a nyphen anu a carriage return displays the specified line and aii 
remaining lines in the program. 

2. A hyphen between the LIST command and Hn-num causes VAX-1 1 BASIC to signal an 
error. 

BP2) BASIC-PLUS-2 

1. A hyphen between the LIST command and the Hn-num displays all lines from the begin- 
ning of the program up to and including the Hn-num you specify. 

2. A Hn-num followed by a comma or a hyphen and a carriage return displays only the 
specified line. 

3. If there are no lines in the specified range, BASIC-PLUS-2 signals an error. 
General Rules 

1. BASIC displays the source program lines in the order you specify in the command line. 
That is, BASIC displays line 100 before line 10 if you type LIST 100,10. 

Examples 

VAX-1 1 BASIC 

LIST 50 t 200-300* 30000- 

BASIC-PLUS-2 

LISTNH -30. 2000-2500. 19000 
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17.0 LOAD 



Function 



The LOAD command makes a previously created object module or modules available for execution 
with the RUN command. 

Format 



LOAD file-spec [ + file-spec ] ... 



Syntax Rules 



1 . File-spec must be a BASIC object module or BASIC signals an error. OBJ is the default file 
type. If you specify only the file name, BASIC searches for an OBJ file in the current default 
directory. 

2. Each device and directory specification applies to all following file specifications until you 
specify a new directory or device. 

3. Each new LOAD command cancels the effect of a previous LOAD command. That is, the 
LOAD command clears all previously loaded object modules from memory. 

4. The LOAD command accepts multiple device, directory, and file specifications. 

General Rules 

1 . BASIC does not process the loaded object files until you issue the RUN command. Conse- 
quently, errors in the loaded modules may not be detected until you execute them. 

2. BASIC signals an error: 

• If the file is not found 

• If the file specification is not valid 

• If the file is not a BASIC object module 

• If run-time memory is exceeded 

Errors do not change the program currently in memory. 

3. Typing the LOAD command does not change the program currently in memory. 

Examples 

LOAD PROGA + PROGB + PROGC 
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18.0 LOCK 

Function 

The LOCK command changes default values for COMPILE command qualifiers. It is a synonym for 
the SET command. See the SET command for syntax rules. 
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ion mpw 

Function 

The NEW command clears BASIC memory and allows you to assign a name to a new program. 

Format 



NEW [ prog-nam 



Syntax Rules 

1. Prog-nam is the name of the program you want to create. VAX-11 BASIC and 
BASIC-PLUS-2 on RSX-1 1M/M-PLUS systems allow names to contain up to nine alpha- 
numeric characters. BASIC-PLUS-2 on RSTS/E systems allows names to contain up to six 
alphanumeric characters. 

2. BASIC-PLUS-2 on RSTS/E systems truncates a prog-nam that exceeds six characters and 
does not signal an error. 

3. VAX-1 1 BASIC and BASIC-PLUS-2 on RSX-U M I M-PLUS systems signal an error if the 
prog-nam exceeds nine characters. 

4. VAX-1 1 BASIC signals "error in program name" if you specify a file type. BASIC-PLUS-2 
ignores the file type and does not signal an error. 

General Rules 

1 . If you do not specify a prog-nam, BASIC prompts with: 
New file name-- 

2. The default name is NONAME. if you do not provide a prog-nam in response to the 
prompt, BASIC assigns the file name NONAME to your program. 

3. When you type the NEW command, the program currently in memory is lost. Program 
modules loaded with the LOAD command remain unchanged. 

Examples 

NEW PR0G1 
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20.0 ODLRMS (BASIC-PLUS-2) 

Function 

The ODLRMS command allows you to select an overlay description (ODL) file to describe the RMS 
overlay structure to be used when your program is task built. When you use the BUILD command, 
BASIC-PLUS-2 includes the specified ODL file in the Task Builder command file. Every system has 
an ODL default set when BASIC-PLUS-2 is installed. See your system manager for the name of vour 
BASIC default. J r 

Format 



ODLRMS [ odl-param ] 



odl-param: 



file-spec 
NONE 



Syntax Rules 

1 . If you enter the ODLRMS command without an odl-param, BASIC-PLUS-2 prompts for 
one and displays the name of the current default ODL file. 

• File-spec can be an ODL file supplied by RMS or a user-created file. Table 15 lists and 
describes RMS ODL files. 

• NONE tells the Task Builder not to link your task to any RMS ODL file. 

• If you type a carriage return in response to the prompt, BASIC-PLUS-2 uses the default 
ODL file. 

General Rules 

1 . New versions of RMS can change ODL file names, so consult the RMS distribution kit for 
current ODL names. LB: is a RSTS/E logical name for the library account on disk. On 
RSX-1 1M/M-PLUS systems, you must specify LB:[1,1] before the ODL file name. 

2. Enter the ODLRMS command before you enter the BUILD command. The ODL file you 
specify is included in all Task Builder command files until you enter a new ODLRMS 
command or exit from the BASIC environment, at which time BASIC-PLUS-2 returns to the 
ODL default file. 

3. You can override the ODLRMS command with the ODL qualifier to the BUILD command 
for a single BUILD operation. 

4. Refer to the RMSRES compiler command to see which ODL files are required for each RMS 
library. 
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The Task Builder returns an error message if the ODL file you select is not available or 
valid. Consult your system manager for information about ODL files available to you. 

Consult BASIC on RSX-1 1M /M-PLUS Systems or BASIC on RSTS/E Systems for more 
information on using RMS libraries. 



Table 15: ODL Files 



ODLRMS 
Option 


File Organization 


Type of 
Library 


Overlay 
Segments 


Seq 


Rel 


Ind 


RMSRLX 


Yes 


Yes 


Yes 


Memory 


None 


DAPRLX 


Yes 


Yes 


Yes 


Memory 


None 


RMS11S 


Yes 


Yes 


No 


Disk 


11 


RMS12S 


Yes 


Yes 


No 


Disk 


5 


RMS11X 


Yes 


Yes 


Yes 


Disk 


35 


RMS1 2X 


Yes 


Yes 


Yes 


Disk 


13 


DAP11X 


Yes 


Yes 


Yes 


Disk 


16 



Examples 

RSX- UMI M-PLUS Systems 

ODLRMS LB:C1 » 1 ] RMSRLX . ODL 

RSTS/E Systems 

ODLRMS LBsRMSRLX.ODL 
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21.0 OLD 

Function 

The OLD command brings a previously created BASIC program into memory. 
Format 



OLD [ file-spec ] 



Syntax Rules 

1 . If you do not name a file-spec, BASIC prompts for one. If you do not enter a file-spec in 
response to the prompt, BASIC searches for a file named NONAME BAS (VAX-1 1 BASIC) 
or NONAME.B2S (BASIC-PLUS-2) in the current default directory ° 

2. The default file type is BAS for VAX-1 1 BASIC and B2S for BASIC-PLUS-2. 
General Rules 

1 ' I f nH e R ^7 pm k? 1 fin ? * e fU H- Pe h y™- 1 ? BASIC si § nals the error " file n ot found" 
and BASIC-PLUS-2 signals "can't find file or account". 

2. When the specified file is found, it is placed in memory and any program currently in 
memory is erased If BASIC does not find the specified file, the program currently in 
memory does not change. 

3. If you specify a file that does not begin with a line number, BASIC discards all text up to the 
first line number, brings the file into memory, and signals the Prror "Nnn-r nt-u-d s^e 
ment has no line number near <line number>". You can then LIST and SAVE^the 
program. 

Examples 

OLD CHECK 
Ready 
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22.0 Qualifiers 



Function 



BASIC qualifiers allow you to specify defaults for the compilation process and the BASIC environ- 
ment. You specify qualifiers with the COMPILE and SET commands. In BASIC-PLUS-2, you can also 
specify qualifiers with the BUILD and RUN commands. 

Format 



f*f\mmanr\ \ /nnalifior 1 



Syntax Rules 



1 . The slash delimiter is not required before the first qualifier in the SET command. Multiple 
qualifiers, however, must be separated by slashes or commas. See the syntax rules for the 
SET command for more information on separating qualifiers. 

2. You can abbreviate all positive qualifiers to the first three letters of the qualifier keyword. 
You can abbreviate a negative qualifier to NO and the first three letters of the qualifier 
keyword. 

General Rules 

1 . Table 1 6 lists VAX-/ 1 BASIC qualifiers and their functions. Table 1 7 lists BASIC-PLUS-2 
qualifiers, the commands they can be used with, and their functions. 

2. In cases of ambiguous or erroneous qualifiers, VAX-1 1 BASIC signals the error "Unknown 
qualifier", while BASIC-PLUS-2 signals "Illegal switch". 

3. When you exit from the BASIC environment, all defaults set with qualifiers return to the 
defaults. Use the SHOW command before setting any qualifiers to display your system 
defaults. 

Examples 

COMPILE /NOQB J /DOUBLE / DEBUG 

SET /TYPE-DEFAULT: EXPLICIT / LIST 
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Table 16: VAX-11 BASIC COMPILE and SET Command Qualifiers 



Qualifier 



[NO]ANSI_STANDARD 



[NO]AUDIT [ sep text-entry ] 



sep: 



text-entry: 



str-lit 
file-spec 



[NO]BOUNDS_CHECK 



BYTE 



[NO]CROSS_REFERENCE [ sep [NO] KEYWORDS 



sep: 



[NO] DEBUG 



Function 



Tells BASIC to compile programs according to the ANSI Minimal 
BASIC Standard and to fiag syntax that does not conform to the 
standard. See BASIC on VAX/VMS Systems for information on 
the ANSI Minimal BASIC Standard. 



Tells BASIC to include a history entry in the CDD data base when 
a CDD definition is extracted. Str-lit is a quoted string. File-spec 
is a text file. The history entry includes: 

• The contents of str-lit, or up to the first 64 lines in the file 
specified by file-spec 

• The name of the program module, process, user name, and 
user UIC that accessed the CDD 

• The time and date of the access 

• A note that access was made by the BASIC compiler 

• A note that the access was an extraction 



Tells BASIC to perform range checks on array subscripts. BASIC 
checks that all subscript references are within the array bound- 
aries set when the array was declared. 



DECIMAL_SIZE sep (d,s) 



sep: 



Causes the compiler to allocate eight bits of storage as the default 
for all integer data not explicitly typed in the program. Untyped 
integer values are treated as BYTE values and must be in the 
BYTE range or BASIC signals the error "Integer error or over- 
flow". Table 2 in this manual lists BASIC data types and ranges. 



Causes the compiler to include cross-reference information in the 
program listing file. If you specify KEYWORDS, BASIC also 
cross-references BASIC keywords used in the program. The list- 
ing file takes the program name as the file name and a default file 
type of LIS. 



Tells BASIC to provide records for the VAX-11 Symbolic 
Debugger. See BASIC on VAX/VMS Systems for information on 
using the VAX- 7 1 Symbolic Debugger. 



Allows you to specify the default size and precision for all 
DECIMAL data not explicitly assigned size and precision in the 
program. You specify the total number of digits (d) and the num- 
ber of digits to the right of the decimal point (s). BASIC signals 
the error "Decimal error or overflow" (ERR =181) when 
DECIMAL values are outside the range specified with this quali- 
fier. See Table 2 in this manual and Appendix C in BASIC on 
VAX I VMS Systems for information on the storage and range of 
packed decimal data. 
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Table 16: VAX-41 BASIC COMPILE and SET Command Qualifiers (Cont.) 



Qualifier 



DOUBLE 



[NO] FLAG [ sep ( flag-clause,... ) ] 



sep: 



flag-clause: 



[NO]BP2COMPATIBILITY| 
[NOIDECLINING I 



Function 



Causes the compiler to allocate 64 bits of storage in 
D_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as DOUBLE values and must be in 
the DOUBLE range or BASIC signals the error "Floating- 
point error or overflow". Table 2 in this manual lists BASIC 
data types and ranges. 



Causes BASIC to provide compile-time information about 
program elements that are not compatible with 
BASIC-PLUS-2 or that DIGITAL designates as declining. 
An element is designated declining when BASIC has a 
preferred and often more powerful way to perform the 
operation. 

If you specify BP2COMPATIBILITY, BASIC will flag the 
following source code as incompatible with 
BASIC-PLUS-2: 

• String comparisons using (<),(>),(< = ), or (> = ) 

• DECIMAL keyword and DECIMAL function 

• HFLOAT keyword 

• GFLOAT keyword 

• LOC function 

• MAR and MAR% functions 

• MARGIN and NOMARGIN statements 

• RECORD declarations 

• More than 1 6 digits of precision in a floating-point literal 

• Explicit literal notation that specifies a radix 

• Explicit literal notation with data type other than "B" 
(BYTE), "W" (WORD), "L" (LONG), "S" (SINGLE), "D" 
(DOUBLE), or "C" (CHARACTER) 

• Names in the EXTERNAL statement that have more than 
six characters or contain characters not in the Radix-50 
character set 

• BY DESC clauses on anything other than entire arrays or 
unsubscripted STRING variables 

• BY VALUE clauses for anything other than BYTE or 
WORD unsubscripted variables 

• More than eight parameters to a DEF, subprogram, or 
external function 
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Table 16: VAX-11 BASIC COMPILE and SET Command Qualifiers (Cont.) 



Qualifier 



GFLOAT 



HFLOAT 



[NO]LINE 



[NOILIST 



Function 



• Arrays of more than eight dimensions 

• Terminal-format files opened with no MAP or 
RECORDSIZE clause and no ACCESS READ clause 

• BY DESC, BY REF, and BY VALUE clauses in SUB and 
FUNCTION statements 

If you specify DECLINING, BASIC will flag the following 
source code as declining: 

• CVT$$ (use EDIT$) 

• CVT$%, CVT$F, CVT%$, CVTF$, and SWAP% (use 
multiple MAP statements) 

• DEF* functions (use DEF functions) 

• FIELD statements (use MAP DYNAMIC and REMAP) 

• GOTO lin-num% (do not use the integer suffix with a 
line number) 



Causes the compiler to allocate 64 bits of storage in 
G_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as GFLOAT values and must be in 
the GFLOAT range or BASIC signals "Floating-point error 
or overflow". Table 2 in this manual lists BASIC data types 
and ranges. 



Causes the compiler to allocate 128 bits of storage in 
H_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as HFLOAT values and must be in 
the HFLOAT range or BASIC signals "Floating-point error 
or overflow". Table 2 in this manual lists BASIC data types 
and ranges. 



Includes line number information in object modules. If you 
specify NOLINE in a program containing a RESUME state- 
ment or using the run-time ERL function, BASIC warns that 
the NOLINE qualifier has been overridden. 



Tells BASIC to produce a source listing file. By default, this 
file contains a memory allocation map. The listing file 
takes the name of the program and a default file type of 
LIS. 

(continued on next page) 
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vav_i 1 RASir COMPILE and SET Command Qualifiers (Cont.) 



Qualifier 



LONG 



[NO]MACHINE_CODE 



[NO] OBJECT 



[NOIOVERFLOW [ sep (data-type,. 



sep: 



data-type: 



INTEGER 
DECIMAL 



[NOIROUND 



[NO] SETUP 



Function 



Causes the compiler to allocate 32 bits of storage as the 
default size for all integer data not explicitly typed in the 
program. Untyped integer values are treated as LONG val- 
ues and must be in the LONG range or BASIC signals the 
error "Integer error or overflow". Table 2 in this manual 

1:^4-*. DA CI/" .-l-i*-* twnor a"^ ronooc 

11313 u/~vjiv_ uaia iy|JCj d.i iu iang^3. 



Causes BASIC to include the machine code generated by 
the compilation in the program listing file. 



Generates an object module with the same file name as the 
program and a default file type of OBJ. Use NOOBJECT to 
check your program for errors without creating an object 
file. 



Tells BASIC to report arithmetic overflow for operations on 
integer and /or packed decimal data. 



Tells BASIC to round rather than truncate DECIMAL 
values. 



Tells BASIC to make calls to the Run-Time Library that set 
up the stack for BASIC variables, set up dynamic string and 
array descriptors, initialize variables, and enable BASIC 
error handling. If you specify NOSETUP, BASIC will 
attempt to optimize your program by omitting these calls. 
If your program contains any of the following elements, 
BASIC provides an informational diagnostic and does not 
optimize your program: 

• CHANGE statements 

• DEF or DEF* statements 

• Dynamic string variables 

• Executable DIM statements 

• EXTERNAL string functions 

• MAT statements 

• MOVE statements for an entire array 

• ON ERROR statements 
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Table 16: VAX-11 BASIC COMPILE and SET Command Qualifiers (Cont.) 



Qualifier 



[NOISHOW [ sep( show-item,... ) 



sep: 



show- item: 



[NO]CDD_DEFINITIONS 

[NOJENVIRONMENT 

[NOjINCLUDE 

[NO]MAP 

[NOIOVERRIDE 



SINGLE 



[NO]SYNTAX_CHECK 



[NOITRACEBACK 



Function 



• READ statements 

• REMAP statements 

• RESUME statements 

• String concatenation 

• Built-in string functions 

• Virtual array declarations 



Note that program modules compiled with NOSETUP 
cannot perform any I/O and have no error handling capa- 
bilities. If an error occurs in such a module, the error is 
resignaled to the calling program. 



Tells BASIC what to include in the listing file: 

• CDD_DEFINITIONS specifies translated CDD defini- 
tions. 

• ENVIRONMENT specifies a listing of the compilation 
qualifiers in effect. 

• INCLUDE specifies a listing of the contents of %IN- 
CLUDE files. 

• MAP specifies a storage allocation map. 

• OVERRIDE cancels the effect of aii %NOLIST directives 
in the source program. 

If you do not specify a show-item, BASIC uses the defaults 
set with the DCL command. 



Causes the compiler to allocate 32 bits of storage in 
F_FLOAT format as the default size for all floating-point 
data not explicitly typed in the program. Untyped floating- 
point values are treated as SINGLE values and must be in 
the SINGLE range or BASIC signals the error "Floating- 
point error or overflow". Table 2 in this manual lists BASIC 
data types and ranges. 



Tells BASIC to perform syntax checking after each program 
line is typed. 



Causes BASIC to include traceback information in the ob- 
ject file that allows reporting of the sequence of calls that 
transferred control to the statement where an error 
occured. 
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Tahlp 16; VAX-11 BASIC COMPILE and SET Command Qualifiers (Cont.) 



Qualifier 



TYPE_DEFAULT sep default-clause 



sep: 



default-clause: 



REAL 
INTEGER 
DECIMAL ( 
EXPLICIT 



VARIANT sep int-const 
sep: j ' 



[NOJWARNINGS [ sep warn-clause ] 
sep: 



warn-clause: 



[NO]WARNINGS 
[NO]INFORMATIONALS 



WORD 



Function 



Sets the default data type (REAL, INTEGER, or DECIMAL) 
for all data not explicitly typed in your program or specifies 
that all data must be explicitly typed (EXPLICIT). 

• REAL specifies that all data not explicitly typed is float- 
ing-point data of the default size (SINGLE, DOUBLE, 
GFLOAT, or HFLOAT). 

• INTEGER specifies that all data not explicitly typed is 
integer data of the default size (BYTE, WORD, or 
LONG). 

• DECIMAL specifies that all data not explicitly typed is 
packed decimal data of the default size. 

• EXPLICIT specifies that all data in a program must be 
explicitly typed. Implicitly declared variables cause 
BASIC to signal an error. 



Establishes int-const as a value to be used in compiler 
directives. The variant value can be referenced in a lexical 
expression by using the lexical function, %VARIANT. 
Int-const always has a data type of LONG. 



Tells BASIC to display warning and /or informational mes- 
sages. If you specify WARNINGS but do not specify a 
warn-clause, BASIC displays both warnings and informa- 
tional messages. 



Causes the compiler to allocate 16 bits of storage as the 
default for all integer data not explicitly typed in the pro- 
gram. Untyped integer values are treated as WORD values 
and must be in the range -32768 to 32767 or BASIC sig- 
nals the error "Integer error or overflow." Table 2 in this 
manual lists BASIC data types and ranges. 
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Table 17: BASIC-PLUS-2 Command Qualifiers 



Qualifier 


Commands 


Function 


BRLRES: lib-paran 
iib-param: 


i 

f i le-spec 
NONE 




BUILD 


Lets you specify a memory-resident library to be 
linked to your program. File-spec can be a library 
supplied with BASIC-PLUS-2 or a user-created 
library. NONE tells the Task Builder not to link 
your task to the default memory-resident library. 
See the BRLRES command syntax rules in this man- 
ual for more information on memory-resident 
libraries. 


BYTE 


COMPILE 

RUN 

SET 


Causes the compiler to allocate eight bits of storage 
as the default for all integer data not explicitly 
typed in the program. Untyped integer values are 
treated as BYTE values and must be in the BYTE 
range or BASIC signals the error "Integer error or 
overflow". Table 2 in this manual lists BASIC data 
types and ranges. 


[NOjCHAIN 


COMPILE** 

RUN** 

SET** 


Enables other programs to CHAIN into the program 
using the LINE clause of the CHAIN statement. The 
default (CHAIN or NOCHAIN) is an installation 
option. If the program has more than 200 line 
numbers, NOCHAIN reduces the memory needs of 
the output program by disabling storage of line 
numbers in memory. You cannot chain from one 
DEC NET node to another. 


[NO]CLUSTER[:!ib-param] 
... ) file-spec 

l,b - param: (none 




SUILD 
SET 


Tells the Task Builder lo cluster memory-resident 
libraries to increase the space available for your 
task. For the cluster qualifier to have an effect, at 
least two resident libraries must be linked to the 
task: the BASIC-PLUS-2 resident library, and one 
other resident library. File-spec specifies a mem- 
ory-resident library to be clustered. NONE speci- 
fies that only the BASIC-PLUS-2 and RMS libraries 
are clustered. 

If there is no default CLUSTER library, the 
CLUSTER qualifier without a parameter acts the 
same as the CLUSTER:NONE qualifier. The speci- 
fied library must be in the account LB: on RSTS/E 
systems or the account LB: [1,1] on RSX systems. 
Consult BASIC on RSX-1 1 M 1 M-PLUS Systems or 
BASIC on RSTS/E Systems for more information on 
using RMS libraries. 


[NO]CROSS_REFERENCE[:[NO]KEYWORDS] 


COMPILE 
SET 


Causes the compiler to include cross-reference 
information in the program listing file. If you spec- 
ify KEYWORDS, BASIC also cross-references 
BASIC keywords used in the program. The listing 
file takes the program name as the file name and a 
default file type of LST. 
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Qualifier 



[NO]DEBUG 



DOUBLE 



Commands 



COMPILE 

RUN 
SET 



COMPILE 

RUN 

SET 



DSKLIB : file-spec 



[NOJDUMP 



EXTEND: int-const 



BUILD 



BUILD 
SET 



BUILD 
SET 



FLAG:[NO]DECLINING 



COMPILE 

RUN 

SET 



Function 



Tells BASIC to provide records for the 
BASIC-PLUS-2 debugger when you compile a pro- 
gram or to pass control to the debugger when you 
execute a program with RUN in the BASIC envi- 
ronment. The LINE qualifier must be in effect when 
you compile a program with the DEBUG qualifier 
in effect. 



Causes the compiler to allocate 64 bits of storage 
as the default size for all floating-point data not 
explicitly typed in the program. Untyped floating- 
point values are treated as DOUBLE values and 
must be in the DOUBLE range or BASIC signals the 
error "Floating-point error". Table 2 in this manual 
lists BASIC data types and ranges. 



Lets you specify a disk-resident object module 
library to be linked to your program. File-spec can 
be a library supplied with BASIC-PLUS-2 or a 
user-created library. NONE tells the Task Builder 
not to link your task to the default object module 
library. See the DSKLIB command syntax rules for 
more information on disk-resident libraries. 



Tells the Task Builder to generate a memory dump 
if the program aborts with a fatal error. 



Specifies the amount of space to be added to the 
initial task size when the task is started. The Task 
Builder rounds the extension up to the nearest 
32-word boundary. The maximum extension is 
32000. 



Causes BASIC to provide compile-time information 
about program elements that DIGITAL designates 
declining. An element is designated declining 
when BASIC has a preferred and often more 
powerful capablity. When you specify 
FLAG:DECLINING, BASIC will flag the following 
source code: 

• CVT$$ (use EDIT$) 

. CVT$%, CVT$F, CVT%$, CVTF$, and SWAP% 
(use multiple MAP statements) 

• DEF* functions (use DEF functions) 
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Table 1 7: BASIC-PLUS-2 Command Qualifiers (Cont.) 



Qualifier 


Commands 


Function 






• FIELD statements (use MAP DYNAMIC and 
REMAP) 

• GOTO lin-num% (do not use the integer suffix 
with a line number) 


[NOJIND 


BUILD 
SET 


Causes the Task Builder to include the code 
needed for indexed file operations. BASIC-PLUS-2 
enables this qualifier automatically for programs 
containing an OPEN statement with an 
ORGANIZATION INDEXED clause. 


LIBRARY: lib-par 
lib-param: 


am 

lib-nam 
file-spec 
NONE 




BUILD 


Lets you specify a memory-resident library to be 
linked to your program. File-spec and lib-nam can 
be a library supplied with BASIC-PLUS-2 or a 
user-created library. If you specify only a lib-nam 
with no device, BASIC assumes LB: on RSTS/E sys- 
tems and LB:[1,1] on RSX systems. NONE tells the 
Task Builder not to link your task to the default 
memory-resident library. Therefore, the Task 
Builder links to the BASIC disk-resident, object 
module library, BP20TS.OLB. See the LIBRARY 
command syntax rules for more information on 
memory-resident libraries. 


[NOjLiNE 


COMPILE 

RUN 

SET 


Includes line number information in object 
modules. If you specify NOLINE in a program con- 
taining a RESUME statement or using the run-time 
ERL function, BASIC warns that the NOLINE quali- 
fier has been overridden. 


[NO]LIST 


COMPILE 
SET 


Tells BASIC to produce a source listing file. The 
listing file takes the name of the program and a 
default file type of LST. 


LONG 


COMPILE 

RUN 

SET 


Causes the compiler to allocate 32 bits of storage 
as the default size for all integer data not explicitly 
typed in the program. Untyped integer values are 
treated as LONG values and must be in the LONG 
range or BASIC signals the error "Integer error". 
Table 2 in this manual lists BASIC data types and 
ranges. 


[NO] MACRO 


COMPILE 
SET 


Converts the program into MACRO source code 
and saves it in a file with the same name as the 
program and a file type of MAC. The MAC file can 
be assembled. 
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Qualifier 


Commands 


Function 


[NO]MAP 


BUILD 


Includes information for the allocation map in the 
Task Builder command file. 


[NO]OBJECT 


COMPILE 
SET 


Generates an object module with the same file 
name as the program and a default file type of OBJ. 

1 Icp MnnRIFfT fn r-hor-W vnur nrnoram fnr errors 

without creating an object file. 


ODLRMS: odl-param 

ji I file-spec 1 

odl-param: 1^ 


BUILD 


Lets you specify an ODL file to describe the RMS 
overlay structure to be used by the Task Builder. 
File-spec can be an ODL file supplied by RMS or a 
user-created file. NONE tells the Task Builder not 
to link your task to the default ODL file. See the 
ODLRMS command syntax rules in this manual for 
more information on ODL files. 


PAGE_SIZE: int-const 


COMPILE 
SET 


Sets the page size for the listing file. Int-const must 
be greater than zero or BASIC signals the warning 
"Listing length out of range — ignored". 


[NO]REL 


BUILD 
SET 


Causes the Task Builder to include the code 
needed for relative file operations. BASIC-PLUS-2 
sets this qualifier automatically for programs con- 
taining an ORGANIZATION RELATIVE clause in 
an OPEN statement. 


RMSRES: lib-param 

1 file-spec ( 
lib-param: j NQNE J 


BUILD 


Lets you specify an RMS library that supplies code 
for file and record operations to be linked to your 
program. File-spec can be a library supplied by 
RMS or a user-created library. NONE tells the Task 
Builder not to link your task to the default RMS 
library. See the RMSRES command syntax rules for 
more information on RMS libraries. 


[NO]SCALE: const 


COMPILE 


Allows control of accumulated round-off errors 
when double precision numbers (values typed 
DOUBLE) are used. Numbers are stored as multi- 
ples of 10 by setting the scale factor (const) from 
to 6. Floating-point numbers are truncated to an 
integer value of to 6. A scale factor larger than 6 
causes BASIC to signal the error message "Scale 
factor of n is out of range." 


[NO]SEQ 


BUILD 
SET 


Causes the Task Builder to include the RMS-11 
code needed for sequential file operations. 
BASIC-PLUS-2 sets this qualifier automatically for 
programs containing an ORGANIZATION 
SEQUENTIAL clause in the OPEN statement. 
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Table 17: BASIC-PLUS-2 Command Qualifiers (Cont.) 



Qualifier 


Commands 


Function 


SINGLE 


COMPILE 


Causes the compiler to allocate 32 bits of storage 




RUN 


as the default size for all floating-point data not 




SET 


explicitly typed in the program. Untyped floating- 
point values are treated as SINGLE values and must 
be in the SINGLE range or BASIC signals the error 
"Floating-point error". Table 2 in this manual lists 
BASIC data types and ranges. 


[NO]SYNTAX_CHECK 


COMPILE 


Tells BASIC to perform syntax checking after each 




RUN 


program line is typed. 




SET 




TYPE_DEFAULT: default-clause 


COMPILE 


Sets the default data type (REAL or INTEGER) for all 




RUN 


data not explicitly typed in your program or speci- 




KbAL 


SET 


fies that all data must be explicitly typed 


default-clause: 


INTEGER 
EXPLICIT ) 




(EXPLICIT). 






• REAL specifies that all data not explicitly typed is 






floating-point data of the default size (SINGLE or 






DOUBLE). 






• INTEGER specifies that all data not explicitly 






typed is integer data of the default size (BYTE, 






WORD, or LONG). 






• EXPLICIT specifies that all data in a program 






must be explicitly typed. Implicitly declared vari- 






ables cause BASIC to signal an error. 


VARIANT: int-const 


COMPILE 


Establishes int-const as a value to be used in com- 




RUN 


piler directives. The variant value can be refer- 




SET 


enced i. a lexical expression by using the lexical 
function, %VARIANT. Int-const always has a data 
type of WORD. 


[NO]VIR 


BUILD* 


Causes the Task Builder to include the RMS code 




SET* 


needed for virtual array and block I /O file opera- 
tions. BASIC-PLUS-2 sets this qualifier automati- 
cally when you compile a program containing an 
ORGANIZATION VIRTUAL clause in the OPEN 
statement. 



(continued on next page) 



94 



BASIC Reference Manual 



Qualifiers 



i auie i / • 



1 /"/vnnrMinH ^^iiiliti<ii<c (ff\r\+ \ 



Qualifier 


Commands 


Function 


WIDTH: int-const 


COMPILE 
SET 


Sets the width of the listing file. Int-const must be 
in the range 72 to 132, inclusive, or BASIC signals 
the warning "Listing width out of range — 
ignored". 


WORD 


COMPILE 

RUN 
SET 


Causes the compiler to allocate 16 bits of storage 
as the default for all integer data not explicitly 
typed in the program. Untyped integer values are 
treated as WORD values and must be in the range 
-32768 to 32767 or BASIC signals the error 
"Integer error." Table 2 in this manual lists BASIC 
data types and ranges. 



* RSX only 
** RSTS/Eonly 
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23.0 RENAME 



Function 



The RENAME command allows you to assign a new name to the program currently in memory. 
BASIC does not write the renamed program to a file until you save the program with the REPLACE or 
SAVE command. 

Format 



i 11 i >i/T.ivii_ ^ yst wy i iui 1 1 j 




Syntax Rules 

1. Prog-nam specifies the new program name. VAX- 7 7 BASIC and BASIC-PLUS-2 on 
R5X-7 7 M I M-PLUS systems allow names to contain up to nine alphanumeric characters. 
BASIC-PLUS— 2 on RSTS/E systems allows names to contain up to six alphanumeric 
characters. 

2. The program you want to rename must be in memory. If you type RENAME with no 
program in memory, BASIC renames the default program, NONAME, to the specified 
prog-nam. 

VAX- 7 7 BASIC <vax 

1 . If you do not specify a prog-nam, VAX-7 7 BASIC renames the program currently in mem- 
ory NONAME. 

2. If you specify a file type, VAX-7 7 BASIC signals the error "error in program name". 
BASIC-PLUS-2 (BP2) 

1 . BASIC-PLUS-2 prompts for the new prog-nam if you do not specify one with the 
RENAME command. If you do not specify a prog-nam in response to the prompt, the name 
of the program currently in memory remains unchanged. 

2. If you specify a file type, BASIC-PLUS-2 ignores the file type, does not signal an error, and 
assigns the B2S file type to the file when you save it. 

General Rules 

1 . You must type SAVE or REPLACE to write the renamed program to a file. If you do not type 
SAVE or REPLACE, BASIC does not save the renamed program. 

2. The RENAME command does not affect the original saved version of the program. For 
example: 

OLD TEST 
Ready 

RENAME NEWTES 
Ready 

SAUE 
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In this example, the OLD command calls the program named TEST into memory. The 
RENAME command renames TEST to NEWTES and the SAVE command writes 
incvV i Lb.dMb wnA-i i dsxjiL) or incvV i tS.ts/s {tsA$i^-Pi_uS-/) to a tile. I ne original tile, 
TEST.BAS or TEST.B2S, is not changed and is not deleted from your account. 



Examples 

RENAME NEWPRO 
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24.0 REPLACE 

Function 

The REPLACE command writes the current program to a storage medium. 

Format 



REPLACE [ file-spec ] 



Syntax Rules 

1 . If you do not supply a file-spec, BASIC writes the program to the default disk with the file 
name of the program currently in memory. 

• VAX-?/ BASIC and BASIC-PLUS-2 on RSX-1 1M/M-PLUS systems create and save a 
new version of the file, incrementing the version number by one. Previous versions of the 
file remain unchanged. 

• BASIC-PLUS-2 on RSTS/E systems overwrites the original version of the file with the 
new version. 

General Rules 

1 . The file-spec does not have to match that of the program currently in memory. You can 
differentiate a changed program from the original version of the program by specifying a 
new file-spec. BASIC saves the program with the new file-spec. 

2. The program currently in memory does not change. 
Examples 

REPLACE PR0GA«NEW 
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25.0 RESEQUENCE (VAX-11 BASIC) 

Function 

The RESEQUENCE command allows you to resequence the line numbers of the program currently in 
memory. BASIC also changes all references to the old line numbers so they reference the new line 
numbers. 

Format 



RESEQUENCE [ Iin-num1 [ - Iin-num2 ] [ Iin-num3 ] ] [ STEP int-const ] 



Syntax Rules 



1. Lin-num1 is the line number in the program currently in memory where resequencing 
begins. The default for lin-numl is the first line of the program module. 

2. Lin-num2 is the optional end of the range of line numbers to be resequenced. If you specify 
a range, BASIC begins resequencing with Iin-num1 and resequences through Iin-num2. If 
you do not specify Iin-num2, BASIC resequences the specified line. If you do not specify 
either lin-numl or Iin-num2, BASIC resequences the entire program. 

3. Lin-num3 specifies the new first line number; the default number for the new first line 
is 100. 

• If Iin-num3 will cause existing lines to be deleted or surrounded, BASIC signals an error. 

• You can specify Iin-num3, the new first line number, only when resequencing a range of 
lines. 

4. Int-const specifies the numbering increment for the resequencing operation. The default for 
int-const is 10. 

5. BASIC signals an error when you try to resequence a program that contains a %IF directive. 
BASIC also signals an error when you try to resequence a program that has a %INCLUDE 
directive if the file to be included contains a reference to a line number. 

General Rules 

1 . Before the RESEQUENCE command executes, BASIC verifies the syntax of the program If 
the program is not syntactically valid, the RESEQUENCE command does not execute. 

2. BASIC sorts the renumbered program in ascending order when the RESEQUENCE com- 
mand executes. 

3. If the renumbering creates a line number greater than the maximum line number of 32767, 
BASIC signals an error. 

4. BASIC signals an error if resequencing causes a change in the order in which program 
statements are to execute and does not resequence the program. 

5. BASIC issues the error "undefined line number" in the case of undefined line numbers and 
does not resequence the program. 
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£ DACir ... 

7. BASIC does not modify the program currently in memory when the RESEQUENCE com- 
mand generates an error. 

8. In general, the RESEQUENCE command is not recommended for programs containing error 
handlers that test the value of ERL. However, the RESEQUENCE command correctly modi- 
fies the program if the tests that reference ERL are of this form: 

ERL relational-operator int-lit 

The RESEQUENCE command does not correctly renumber programs if the test compares 
ERL with an expression or a variable, or if ERL follows the relational operator. The follow- 
ing line number references, for example, would not be correctly renumbered: 



IF ERL = 1000 + A% THEN 
IF 1000 > ERL THEN . , . 

Examples 

RESEQUENCE 100-1000 STEP 5 



♦ ♦ 4 
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RMSRES 

26.0 RMSRES (BASIC-PLUS-2) 

Function 

The RMSRES command allows you to select an RMS memory-resident library to be used when your 
program is task built. You can also choose to use no RMS memory-resident library. The RMS library 
supplies RMS code for file and record operations. After you specify a library with the RMSRES 
command, when you use the BUILD command, BASIC-PLUS-2 includes the specified library in the 
Task Builder command file. Every system has an RMS library default set when BASIC-PLUS-2 is 
installed. 

Format 



RMSRES lib-param 



lib-param: 



file-spec 
NONE 



Syntax Rules 



1 . If you enter the RMSRES command without a lib-param, BASIC-PLUS-2 prompts for one 
and displays the name of the current default RMS library. 

• File-spec can be RMSRES (the RMS memory-resident library) or a user-created resident 
library. Table 18 lists and describes RMS libraries. 

• NONE tells the Task Builder not to link your task to the RMS default resident library. 
Therefore, the Task Builder links to the RMS object module library, RMSLIB.OLB. 

• If you type a carriage return in response to the prompt, the current default memory- 
resident library is used. 



General Rules 



1. LB: is a RSTS/E logical name for the library account on disk. On RSX-11 M I M-PLUS 
systems, you must specify LB: [1,1] before the ODL file name. 

2. BASIC-PLUS-2 links the specified RMS library to your program when you task-build the 
program. You must use the RMSRES command before you use the BUILD command to 
include the specified library in the Task Builder command file. 

3. If you use an RMS library other than the default, you must specify one of the RMS ODL 
files listed in Table 18. See the ODLRMS compiler command for more information. 
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your 



idsk Builder (.ommdrid files until you 



specify a new library with the RMSRES command or exit from the BASIC environment. 
When you exit from the environment, the original RMS default library is restored as the 
default. 

You can override the RMSRES command with the /RMSRES qualifier added to the BUILD 
command, but the specified library remains in effect for only one BUILD routine. 

The Task Builder returns an error message when the requested library is not available. 

Consult your system manager for information about the RMS libraries available to you. 
Consult BASIC on RSX-1 1M IM-PLUS Systems or BASIC on RSTS/E Systems for more 
information on using RMS libraries 



Table 18: RMS Libraries 



Library 
Name 


File Organization 


Type of 
Library 


ODL File 
Required 


Seq 


Rel 


Ind 


RMSRES 


Yes 


Yes 


Yes 


Memory 


RMSRLX.ODL 


DAPRES 


Yes 


Yes 


Yes 


Memory 


DAPRLX.ODL 
, RMS11S.ODL\ 
\ RMS12S.ODL / 


RMSLIB 


Yes 


Yes 


Yes 


Disk 


<RMS11X.ODL> 
/RMS12X.ODL\ 
' DAP11X.ODL ' 



Examples 

RSX-1 1 M I M-PLUS Systems 

RMSRES LBsCl >1]RMSRES 

RSTS/E Systems 

RMSRES LB: RMSRES 
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27.0 RUN and RUNNH 

Function 

The RUN command allows you to execute a program from the BASIC environment without first 
invoking the PDP-11 Task Builder or the VAX-1 7 Linker to construct an executable image. The 
program can be: 

• A BASIC program brought into memory with the OLD command, created in response to the NEW 
command, or specified in the RUN command 

• An object module or modules placed in memory with the LOAD command 

• A combination of the above 

RUN executes the program starting at the lowest line number. Program modules previously compiled 
and placed in memory with the LOAD command are referenced when the RUN command is given. 
RUNNH executes the program but does not display the program header. 

Format 



;VAX> VAX-11 BASIC 



RUNNH 
RUN 



[ file-spec 



(BP2) BASIC-PLUS-2 



RUNNH 
RUN 



file-spec ] [ /qualifier ]... 



Syntax Rules 

1 . If you specify only the file name, BASIC searches for a file with a BAS (VAX- 7 7 BASIC) or 
B2S (BASIC-PLUS-2) file type in the current default directory. 

2. If you do not supply a file-spec, BASIC executes the program currently in memory. 

3. BASIC signals the warning message "No main program" if you do not supply a file-spec 
and do not have a program currently in memory. 

4. The RUNNH command is identical to RUN, except that it does not display the program 
header, current date, and time. 

BASIC-PLUS-2 

1. /Qualifier specifies a qualifier keyword that sets a BASIC default. See Section 22.0 for 
information on BASIC qualifiers. Table 17 lists all BASIC-PLUS-2 qualifiers and the com- 
mands they can be used with, and describes their functions. 

2. Support for RUN is an installation option. Use the SHOW command to see whether your 
system supports the RUN command. 
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General Rules 

1 . When you specify a file-spec with the RUN command, BASIC brings the program into 
memory and then executes it. You do not have to bring a program into memory with the 
OLD command in order to run it. The RUN command executes just as if the program had 
been brought into memory with the OLD command. 

2. If your program calls a subprogram, the subprogram must be compiled and placed in 
memory with the LOAD command. If your program tries to call a subprogram that has not 
been compiled and loaded, BASIC signals an error. 

3. The RUN command does not create an object module file or a listing file. 
VAX-11 BASIC <vax) 

1 . The program stops executing and control passes to the BASIC environment and immediate 
mode when BASIC encounters a STOP statement in the program. 

• Any BASIC statement that does not require the creation of new storage can be entered in 
immediate mode to debug the program. You cannot create new variables in immediate 
mode. 

• Type the CONTINUE command to resume program execution. 

2. The RUN command uses whatever qualifiers have been set with the exception of those that 
have no effect on a program running in the environment. These are: 

• NOCROSS 

• NODEBUG 

• NOLIST 

• NOMACHINE 

• NOOBjECT 
These qualifiers are always in effect when you run a program in the environment. 

BASIC-PLUS-2 (an) 

1 . The program stops executing when BASIC encounters a STOP statement: 

• If you used the RUN command to execute the program, BASIC displays a pound sign (#) 
prompt. In response to the prompt, you can type only CONTINUE to resume program 
execution, or EXIT to end the program. 

• If you used the RUN /DEBUG command to execute the program, control passes to the 
BASIC-PLUS-2 debugger. You can then use BASIC-PLUS-2 debugger commands to 
display and change program values and to analyze your program. Use the CONTINUE 
debugger command to resume program execution. See Part VI in this manual for more 
information on debugger commands. 

Examples 

RUN PR0G1 
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SAVE 
28.0 SAVE 

Function 

The SAVE command writes the BASIC source program currently in memory to a file on the default or 
specified device. 

Format 



SAVE [ file-spec ] 



Syntax Rules 



1. If you do not supply a file-spec, BASIC saves the file with the name of the program 
currently in memory and the BAS {VAX-1 1 BASIC) or B2S (BASIC-PLUS-2) default file 
type. 

2. If you specify only the file name, BASIC saves the program with the default file type in the 
current default directory. 

General Rules 

1 . In BASIC-PLUS-2, if you type SAVE and the file-spec already exists as a disk file, BASIC 
displays the message "File exists - Rename or Replace". 

2. VAX- 7 / 6A5/C writes a new version of a previously saved program when you type the 
SAVE command. 

3. BASIC stores the sorted program in ascending line number order. 

4. You can store the program on a specified device. For example: 

SAVE DBA1:NEWTST.PR0 

BASIC saves the file NEWTST.PRO on disk DBA1 :. 
Examples 

SAVE JUNK, BAS 
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29.0 SCALE 

Function 

The SCALE command allows you to control accumulated round-off errors by multiplying numeric 
values by 10 raised to the scale factor before storing them. 

Format 



SCALE int-const 



Syntax Rules 



1 . In BASIC-PLUS-2, SCALE with no argument causes BASIC to display the message "Current 
scale factor is n", where n is an integer from to 6 inclusive. In VAX-7 7 BASIC, SCALE 
with no argument causes BASIC to signal the error "illegal argument for command". 

2. Int-const specifies the power of 10 you want to use as the scaling factor. 

• In VAX-7 7 BASIC, int-const must be an integer from to 6, inclusive, or BASIC signals 
the error "illegal argument for command". 

• In BASIC-PLUS-2, int-const can be a floating-point or integer number up to 6.999999. 
BASIC truncates a floating point value and displays the message "%Scale factor has been 
truncated to n", where n is the integer portion of the value. If the specified value is 
greater than 6.999999, BASIC signals the error "Scale factor of n is out of range", where 
n is the specified value. 



General Rules 



.E affects only values of the data type DOUBLE. 



2. BASIC multiplies values using the scale factor you specify. The vaiue 2.488888, for 
example, is rounded as follows: 



Scale: 


Produces: 





2.48889 


1 


2.4 


2 


2.48 


3 


2.488 


4 


2.4888 


5 


2.48888 


6 


2.48889 



Examples 



SCALE 2 
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30.0 SCRATCH 

Function 

The SCRATCH command clears any program currently in memory, removes any object files loaded 
with the LOAD command, and resets the program name to NONAME. 

Format 



SCRATCH 



Syntax Rules 

None. 

General Rules 

None. 

Examples 

SCRATCH 
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44 n ecni ICMAE 



Function 



The SEQUENCE command causes BASIC to automatically generate line numbers for your program 
text. BASIC supplies line numbers for your text until you end the procedure or reach the maximum 
line number of 32767. 



Format 



SEQUENCE [ lin-num ] [ , int-const ] 



Syntax Rules 

1 . Lin-num specifies the line number where sequencing begins. 

• If you do not specify a lin-num, the VAX-1 1 BASIC default is the last line inserted by a 
SEQUENCE command; if there is no previous SEQUENCE command, the default is line 
number 100. 

• The BASIC-PLUS-2 default lin-num is always line number 100. 

2. Int-const specifies the line number increment for your program, 

• If you do not specify an increment, VAX-1 1 BASIC defaults to the int-const specified in 
the last SEQUENCE command; if there is no previous SEQUENCE command, the default 
is 10. 

• BASIC-PLUS-2 always defaults to 10. 

General Rules 

1 . If you specify a lin-num that already contains a statement, or if the sequencing operation 
generates a line number that already contains a statement, BASIC signals "Attempt to 
sequence over existing statement", and returns to normal input mode. 

2. Enter your program text in response to the line number prompt; the carriage return ends 
each line and causes BASIC to generate a new line number. 

3. If you enter a CTRL/Z in response to the line number prompt, BASIC terminates the 
sequencing operation and prompts for another command. 

4. You can also terminate the sequence operation in BASIC— PLUS-2 by typing a carriage 
return in response to the line number prompt. 

5. When the maximum line number of 32767 is reached, BASIC terminates the sequencing 
process and returns to normal input mode. 

6. BASIC does not check syntax during the sequencing process. 
Examples 

SEQUENCE 100*10 
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32.0 SET 

Function 

The SET command allows you to specify BASIC defaults for all BASIC qualifiers. Qualifiers control the 
compilation process and the run-time environment. Qualifiers are set or reset as you specify. The 
defaults you set remain in effect for all subsequent operations until they are reset or until you exit from 
the compiler. 

Format 





Syntax Rules 

1. /Qualifier specifies a qualifier keyword that sets a BASIC default. See Section 22.0 for 
information on BASIC qualifiers. Table 16 lists and describes all VAX-1 1 BASIC qualifiers. 
Table 17 lists and describes all BASIC-PLUS-2 qualifiers. 

(vax> 2. If you do not specify any qualifiers, VAX-1 1 BASIC resets all defaults to the defaults 

specified with the DCL BASIC command. 

(BP2) 3. If you do not specify any qualifiers, BASIC-PLUS-2 resets all qualifiers except those set 

^-^ with the BRLRES, DSKLIB, LIBRARY, ODLRMS, RMSRES, or EXTEND qualifier to the 

installation defaults. The SCALE value set with the SCALE command is also not reset to the 

installation default. 

4. VAX-7 / BASIC signals the error "unknown qualifier" and BASIC-PLUS-2 signals "Illegal 
switch" if you do not separate multiple qualifiers with commas or slashes, or if you mix 
commas and slashes on the same command line. The same error is signaled if you separate 
qualifiers with a slash but do not prefix the first qualifier with a slash. 

General Rules 

None. 

Examples 

SET /DOUBLE/BYTE/LIST 
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Function 

The SHOW command displays the current defaults for the BASIC compiler on your terminal. 

Format 




Syntax Rules 

None. 

General Rules 

None. 

Examples 

VAX-1 1 BASIC 

SHOW 

VAX-li BASIC V2. Current Environment 

DEFAULT DATA TYPE INFORMATION: 

Data type s REAL 

Real size : SINGLE 

Integer size : LONG 

Decimal size : (15*2) 

Scale factor : 

NO Round decimal numbers 

COMPILATION QUALIFIERS IN EFFECT: 

Object file 

Overflow check integers 

Overflow check decimal numbers 

Bounds checking 
NO Syntax checking 

Lines 

Variant : 

Warnings 

Inf ormationals 

Setup 

Object Libraries : NONE 
Ready 



Status 11-DEC-1S82 10:05:56,57 
LISTING FILE INFORMATION INCLUDES! 
NO Source 
NO Cross reference 

CDD Definitions 

Envi ronment 
NO Override of ZNOLIST 
NO Machine code 

Map 

INCLUDE files 

FLAGGERS: 

Declining features 
NO BASIC PLUS 2 subset 



DEBUG INFORMATION: 

Traceback records 
NO Debug symbol records 



BASIC-PLUS-2 



SHOW 

PDP-11 BASIC-PLUS-2 V2.0 
ENVIRONMENT INFORMATION: 
Current edit line : 
NO Modules loaded 
NO Main module loaded 
Run support 



RMS FILE ORGANIZATION! 
NO Index 
NO Relative 
NO Sequential 
NO Virtual 



(continued on next page) 
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SHOW 



DEFAULT DATA TYPE INFORMATION: 


LISTING FILE INFORMATION: 


Data type : REAL 


NO Source 




Real size : SINGLE 


NO Cross Reference 


Integer size : WORD 


NO Keywords 




Scale factor : 


SO lines by 


132 columns 


COMPILATION QUALIFIERS: 


BUILD QUALIFIERS: 




NO Object 


NO Dump 




NO Macro 


NO Map 




Lines 


Task extend : 


512 


NO Debus records 


RMS ODL file : 


LB:RMSRLX 


NO Syntax checking 


BP2 Disk lib : 


LB:BP20TS 


Flatf : Decl ininS 


BP2 Resident 1: 


ib : LB:BP2RES 


Variant : 


RMS Resident 1: 


ib : LB:RMSRES 
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34.0 UNSAVE 

Function 

The UNSAVE command deletes a specified file from storage. 

Format 



UNSAVE [ file-spec 



Syntax Rules 

1. File-spec is optional. 

• If you do not supply a file-spec, BASIC deletes a file that has the file name of the program 
currently in memory and a file type of BAS (VAX-7 7 BASIC) or B2S (BASIC-PLUS-2). 

• If you do not supply a file-spec and do not have a program in memory, BASIC searches 
for the default file NONAME.BAS. 

2. You do not have to supply a full file-spec. If you specify only a file name, BASIC deletes the 
file with the specified name and the BAS (VAX-7 7 BASIC) or B2S {BASIC-PLUS-2) file type 
from the default device and directory. Other file types with the same file name are not 
deleted. 

General Rules 

1 . The program currently in memory does not change even when it is the deleted file because 
it is a copy of the deleted file. 

Examples 

UNSAVE DB2:CHECK,DAT 
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PART III 

Compiler 

Directives 



%ABORT 



1.0 %ABORT 

Function 

The %ABORT directive terminates program compilation and displays a fatal error message you 
supply. 

Format 



%ABORT [ str-lit ] 



Syntax Rules 

1 . The %ABORT directive cannot begin in column one. 

2. Only a line number or a comment field can appear on the same physical line as the 
%ABORT directive. 

General Rules 

1. BASIC stops the compilation and terminates the listing file as soon as it encounters a 
%ABORT directive. Str-lit is displayed on the terminal screen and in the compilation 
listing, if one has been requested. 

Examples 

100 ZIF XYARIANT = 2 XTHEN 

XABORT "Cannot compile with variant 2" 
XEND %IF 
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%CROSS 
2.0 %CROSS 

Function 

The %CROSS directive causes BASIC to begin or resume accumulating cross-reference information 
for the listing file. 

Format 



%CROSS 



Syntax Rules 

1 . The %CROSS directive cannot begin in column one. 

2. Only a line number or a comment field can appear on the same physical line as the 
%CROSS directive. 

General Rules 

1 . When a cross-reference is requested, the compiler starts or resumes accumulating cross- 
reference information immediately after encountering the %CROSS directive. 

Examples 

1000 ACROSS 
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3.0 %IDENT 



Function 



The %IDENT directive lets you identify the version of a program module. The identification text is 
placed in the object module and printed in the listing header. 



Format 



7olUtlN I sir-in 



Syntax Rules 



1 . Str-lit is the identification text. VAX-1 1 BASIC allows str-lit to consist of up to 31 ASCII 
characters. BASIC-PLUS-2 allows str-lit to consist of up to six RAD-50 characters. Both 
truncate extra characters from str-lit and signal a warning message. 

2. In BASIC-PLUS-2, if str-lit contains non-RAD-50 characters, a warning message is (BP2) 
issued, and the %IDENT directive is ignored. See BASIC on RSX-1 1M/M-PLUS Systems K ~ y 
or BASIC on RSTS/E Systems for more information on RAD-50 characters. 

3. The %IDENT directive cannot begin in column one. 

4. Only a line number or a comment field can appear on the same physical line as the 
%IDENT directive. 



General Rules 



The compiler inserts the identification text in the first 6 or 31 character positions of the 
second line on each listing page. The compiler also includes the identification text in the 
object module, if the compilation produces one, and in the map file created by the Task 
Builder (BASIC-PLUS-2) or the VAX-1 1 Linker. 

The %IDENT directive shouid appear at the beginning of your program if you want the 
identification text to appear on the first page of your listing, if the %IDENT directive 
appears after the first program statement, the text will appear on the next page of the listing 
file. 

You can use the %IDENT directive only once in a module. If you specify more than one 
%IDENT directive in a module, BASIC signals a warning and uses the identification text 
specified in the first %IDENT. 
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%IDENT 



(W) 4. The default BASIC-PLUS-2 identification text is a 6— digit number. The first two digits 

rpnrp<;pnt thp rnmnilpr hacp IpvpI whilp t\na lact fr-wcr finite rcmrocar-,* tUr. m^^tk ->r,^l ,4-.., 
. — P-. H. i..„ ..j^..w v «^w .^f^i; ..tiii^ ».i i ^. H.WI iwwi ui^hj i^^itjtm uic inuiiiii en iu uay. 

For example, the identification text 100712 represents base level 10, and a date of July 12. 




vax> 5. VAX-1 7 BASIC does not provide a default identification text. 



Examples 

100 % I DENT "V3,2" 



116 BASIC Reference Manual 



%!F-%THEN-%EISE-%END-%!F 
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Function 



The %IF-%THEN-%ELSE-%END-%IF directive lets you conditionally include source code or exe- 
cute another compiler directive. 

Format 



%!F !ex-ex n %THEN code [ %ELSE code ] %END %!F 



Syntax Rules 

1 . The %IF directive can appear anywhere in a program where a space is allowed, except in 
column one or within a quoted string. This means that you can use the %IF directive to 
make a whole statement, part of a statement, or a block of statements conditional. 

2. Lex-exp is always a LONG integer in VAX-1 1 BASIC and a WORD integer in 
BASIC-PLUS-2. It can be: 

• A lexical constant named in a %LET directive. 

• An integer literal, with or without the percent sign suffix. 

• A lexical built-in function (%VARIANT). 

• Any combination of the above, separated by valid lexical operators. Lexical operators 
include logical operators, relational operators, and the arithmetic operators for addition 
( + ), subtraction (-), multiplication (*), and division (/). 

3. Code is BASIC program code. It can be any BASIC statement or another compiler directive, 
including another %!F directive. You can nest %IF directives to eight levels. 

4. %THEN, %ELSE, and %END %IF do not have to be on the same physical line as %IF. 

General Rules 

1. If lex-exp is true, BASIC processes the %THEN clause. If lex-exp is false, BASIC processes 
the %ELSE clause. If there is not an %ELSE clause, BASIC processes the %END %IF clause. 
The compiler includes statements in the %THEN or %ELSE clause in the source program 
and executes directives in order of occurrence. 

2. You must include the %END %IF clause. Otherwise, BASIC assumes the remainder of the 
program is part of the last %THEN or %ELSE clause and signals the error "missing %END 
%IF" when compilation ends. 
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%IF-%THEN-%ELSE-%END-%IF 



Examples 

100 ZIF <ZYARIANT = 2) 

%THEN DECLARE SINGLE HOURLY. PAY ( 100 ) 

%ELSE %IF (ZVARIANT = 1) 

ZTHEN DECLARE DOUBLE SALARY _ PAY ( 100 ) 

ZELSE ZABORT "Can't compile with specified variant" 

ZEND ZIF 

ZEND ZIF 



1000 PRINT ZIF (ZVARIANT = 2) 

ZTHEN PRINT 'Hourly Wase Chart' 

GOTO Hourly _ routine 
ZELSE PRINT 'Salaried WaSe Chart' 

GOTO Sal a ry _ rout ine 
ZEND ZIF 
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%INCLUDE 



e a o/ im/^i line 
O.u /oiiwuuue 

Function 

The %INCLUDE directive lets you include BASIC source text from another program file in the current 
program compilation. VAX-1 1 BASIC also lets you access record definitions in the VAX-1 1 Common 
Data Dictionary (CDD). 

Format 

\Jciiaai 



%INCLUDE file-spec 



VAX-1 1 BASIC 



%INCLUDE %FROM %CDD str-lit 




;VAX) 




Syntax Rules 

1. The %INCLUDE directive cannot begin in column one. 

2. Only a line number or a comment field can appear on the same physical line as the 
%INCLUDE directive. 

3. File-spec specifies the file to be included. BASIC uses the default device, directory, and file 
type (BAS in VAX-1 1 BASIC and B2S in BASIC-PLUS-2) if you do not specify these parts of 
the file specification. 

4. File-spec must be a disk file or BASIC signals an error. 

5. File-spec must be a string literal enclosed in quotation marks. 
VAX-1 1 BASIC only <vax) 

1 . Str-lit specifies a VAX-1 1 CDD path specification. This lets you extract a RECORD defini- 
tion from the CDD. 

2. There are two types of CDD path names: absolute and relative. An absolute path name 
begins with CDD$TOP and specifies the complete path to the record definition. A relative 
path name begins with any string other than CDD$TOP. 

General Rules 

1. The compiler includes the specified source file in the program compilation at the point of 
the %INCLUDE directive and prints the included code in the program listing file if the 
compilation produces one. 

2. The included file cannot contain line numbers or BASIC signals the error "Line number 
may not appear in %INCLUDE file". 
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%INCLUDE 



3. All statements in the accessed file are associated with the line number of the program line 
that contains the %INCLUDE directive. This means that a %INCLUDE directive cannot 
appear before the first line number in a source program. 

4. A file accessed by %INCLUDE can itself contain a %INCLUDE directive. 

5. All %IF directives in an included file must have a matching %END %IF directive in the file. 
vax> VAX- 7 1 BASIC only 

1. You can control whether or not included text appears in the compilation listing with the 
/SHOW:INCLUDE qualifier. When you specify /SHOWMNCLUDE, the compilation list- 
ing file identifies any text obtained from an included file by placing a mnemonic in the first 
character position of the line on which the text appears. The mnemonic is of the form "In" 
where "I" tells you that the text was accessed with a %INCLUDE directive and "n" is a 
number that tells you the nesting level of the included text. See the BASIC User's Guide for 
more information on listing mnemonics. 

2. When you use the %INCLUDE directive to extract a record definition from the CDD, 
BASIC translates the CDD definition to the syntax of the BASIC RECORD statement. 

3. You can use the /SHOW:CDD_DEFINITIONS to specify that translated CDD definitions 
(in RECORD statement syntax) are included in the compilation listing file. BASIC places a 
"C" in column one when the translated RECORD statement appears in the listing file. 

4. When you do not specify /SHOW:CDD_DEFINITIONS, BASIC includes the names, data 
types, and offsets of the CDD record components in the program listing's allocation map. 

5. See BASIC on VAX I VMS Systems and the VAX- J J Common Data Dictionary Utilities 
Reference Manual for more information on CDD definitions. 

Examples 

General 

100 ^INCLUDE "YESNO" 

VAX- 7 1 BASIC only 

1000 ^.INCLUDE %FR0M XCDD "CDD$T0P , EMPLOYEE" 
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%LET 



D.U 7ol_C 9 



Function 

The %LET directive declares and provides values for lexical constants. You can use lexical constants 
only in conditional expressions in the %IF-%THEN-%ELSE directive and in lexical expressions in 
subsequent %LET directives. 



Format 



%LET %lex-const-nam = lex-exp 



Syntax Rules 

1. Lex-const-nam is the name of a lexical constant. Lexical constants are always LONG 
integers in VAX-/ 1 BASIC and WORD integers in BASIC-PLUS-2. 

2. Lex-const-nam must be preceded by a percent sign and cannot end with a dollar sign ($) or 
percent sign. 

3. Lex-exp can be: 

• A lexical constant named in a previous %LET directive. 

• An integer literal, with or without the percent sign suffix. 

• A lexical built-in function (% VARIANT) 

• Any combination of the above, separated by valid lexical operators. Lexical operators 
may be logical operators, relational operators, and the arithmetic operators for addition 
( + )', subtraction (-), multiplication (*), and division (/}. 

4. The %LET directive cannot begin in column one. 

5. Only a line number or a comment field can appear on the same physical line as the %LET 
directive. 

General Rules 

1. You cannot change the value of lex-const-nam within a program unit once it has been 
named in a %LET directive. 

Examples 

100 XLET XDEBUCON = IX 
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7.0 %LIST 

Function 

The %LIST directive causes the compiler to start or resume accumulating compilation information for 
the program listing file. 

Format 



%LIST 



Syntax Rules 

1. The %LIST directive cannot begin in column one. 

2. Only a line number or a comment field can appear on the same physical line as the 
%LlST directive. 

General Rules 

1 . As soon as it encounters the %LIST directive, the compiler starts or resumes accumulating 
information for the program listing file. Thus, the directive itself appears as the next line in 
the listing file. 

2. The %LIST directive has no effect unless you requested a listing file. 
Examples 

100 XLIST 
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%NOCROSS 



Function 

The %NOCROSS directive causes the compiler to stop accumulating cross-reference information for 
the program listing file. 

Format 



%NQCROSS 



Syntax Rules 

1 . The %NOCROSS directive cannot begin in column one. 

2. Only a line number or a comment field can appear on the same physical line as the 
%NOCROSS directive. 

General Rules 

1. The compiler stops accumulating cross-reference information for the program listing file 
immediately after encountering the %NOCROSS directive. 

2. The %NOCROSS directive has no effect unless you requested cross-reference 
information. 

3. Digital recommends that you not embed a %NOCROSS directive within a statement. 
Embedding a %NOCROSS directive within a statement makes the accumulation of cross- 
reference information behave unpredictably. 

Examples 

1000 XNDCRDBS 
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%NOLIST 

9.0 %NOLIST 

Function 

The %NOLIST directive causes the compiler to stop accumulating compilation information for the 
program listing file. 

Format 



%NOLIST 



Syntax Rules 

1 . The %NOLIST directive cannot begin in column one. 

2 ' ??!L a J' n€ ; nUmber ° r a comment field can aPPear on the same physical line as the 
%NOLIST directive. 

General Rules 

1 . As soon as it encounters the %NOLIST directive, the compiler stops accumulating informa- 
tion for the program listing file. Thus, the directive itself does not appear in the listing file. 

2. The %NOLIST directive has no effect unless you requested a listing file. 

3. In VAX-11 BASIC, you can override all %NOLIST directives in a program with the 
/SHOW:OVERRIDE qualifier. P 8 

Examples 

100 "ZNOLIST 



124 BASIC Reference Manual February 1984 



%PAGE 



10.0 %PAGE 



Function 



The %PAGE directive causes BASIC to begin a new page in the program listing file immediately after 
the line that contains the %PAGE directive. 

Format 



%PAGE 



Syntax Rules 

1 . The %PAGE directive cannot begin in column one. 

2. Only a line number or a comment field can appear on the same physical line as the 
%PAGE directive. 

General Rules 

None. 

Examples 

1000 XPAGE 
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%SBTTL 
11.0 %SBTTL 

Function 

The %SBTTL directive lets you specify a subtitle for the program listing file. 

Format 



%SBTTL str-lit 



Syntax Rules 



1. VAX-11 BASIC allows str-lit to contain 45 characters. BASIC-PLUS-2 allows str-lit to 
contain 48 characters. 

2. BASIC truncates extra characters from str-lit and does not signal a warning or error. 

3. The %SBTTL directive cannot begin in column one. 

4. Only a line number or a comment field can appear on the same physical line as the 
%SBTTL directive. 

General Rules 

1 . The specified subtitle appears underneath the title on the second line of all pages of the 
listing file until the compiler encounters another %SBTTL or %TITLE directive. 

2. Because BASIC assumes that a subtitle is associated with a title, a new %TITLE directive 
eliminates the current subtitle. In this case, no subtitle appears in the listing until the 
compiler encounters another %SBTTL directive. 

3. If you want a subtitle to appear on the first page of your listing, the %SBTTL directive 
should appear at the beginning of your program, immediately after the %TITLE directive. 
Otherwise, the subtitle will appear on the second page of the listing, but not on the first. 

4. If you want the subtitle to appear on the page of the listing that contains the %SBTTL 
directive, the %SBTTL directive should immediately follow a %PAGE directive or a %TITLE 
directive that follows a %PAGE directive. 

Examples 

100 XSBTTL 'DESMA219 Production Elements' 
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12.0 %TITLE 

Function 

The %TITLE directive lets you specify a title for the program listing file. 

Format 



%TITLE str-lit 



Syntax Rules 



1. VAX-11 BASIC allows str-lit to contain 45 characters. BASIC-PLUS-2 allows str-lit to 
contain 48 characters. 

2. BASIC truncates extra characters from str-lit and does not signal a warning or error. 

3. The %TITLE directive cannot begin in column one. 

4. Only a line number or a comment field can appear on the same physical line as the 
%TITLE directive. 

General Rules 

1. The specified title appears on the first line of every page of the listing file until BASIC 
encounters another %TITLE directive in the program. 

2. The %TITLE directive should appear on the first line of your program, before the first 
statement, if you want the specified title to appear on the first page of your listing. 

3. !f you want the specified title to appear on the page that contains the %T!TLE directive, the 
%TITLE directive should immediately follow a %PAGE directive. 

4. Because BASIC assumes that a subtitle is associated with a title, a new %TITLE directive 
eliminates the current subtitle. 

Examples 

100 ZTITLE 'Production Control for DESMA219' 
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%VARIANT 

13.0 %VARIANT 

Function 



%VARIANT is a built-in lexical function that allows you to conditionally control program compila- 
tion. %VARIANT returns an integer value when you reference it in a lexical expression. You set the 
variant value with the /VARIANT qualifier when you compile the program or with the SET command. 



Format 



%VARIANT 



Syntax Rules 

1 . The % VARIANT function can appear only in a lexical expression. 

General Rules 

1. The %VARIANT function returns the integer value specified at compile-time with the 
/VARIANT qualifier to the COMPILE command or with the SET command, or in VAX-1 7 
BASIC, set with the DCL BASIC command. The returned integer always has a data type of 
LONG in VAX-1 1 BASIC and WORD in BASIC-PLUS-2 . 

Examples 

100 XIF (XLOOP. CONST <= XVARIANT) 
XTHEN GOTO Tax _ Rout ine 

XEL3E XABORT 'Variant too iarSe for program to compile' 
XEND XIF 
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PART IV 
Statements 



CALL 



1.0 CALL 



Function 



The CALL statement transfers control to a BASIC subprogram or other callable routine. You can pass 
optional arguments to the routine and can specify how these arguments are to be passed. When the 
called routine finishes executing, control returns to the calling program. 

Format 



CALL routine [ pass-mech ] [ ( [ actual-param ],... ) ] 



routine: 


I sub-nam 










j any callable routine 




pass-mech: 


( BY REF 

BY VALUE 
I BYDESC 




actual-param: 


I ex P 






j array ( [,]... 


) 


[P 


ass-mech ] 



Syntax Rules 

1. Routine is the name of the BASIC SUB subprogram you want to call or the name of any 
other callable module, such as a system service or an RTL routine on VAX/ VMS systems. It 
cannot be a variable name. 
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2. Pass-mech specifies how arguments are passed to the called routine. If you do not specify a 
pass-mech, BASIC passes arguments as indicated in Tables 19 and 20. 

3. You can use passing mechanisms only when calling non-BASIC routines. 

4. When pass-mech appears before the parameter list, it applies to all arguments passed to the 
called routine. You can override this passing mechanism by specifying a pass-mech for 
individual arguments in the actual-param list. 

5. Actual-param lists the arguments to be passed to the called routine. 

6. You can pass expressions or entire arrays. Optional commas in parentheses after the array 
name specify the dimensions of the array. The number of commas is equal to the number 
of dimensions minus one. Thus, no comma specifies a one-dimensional array, one comma 
specifies a two-dimensional array, two commas specify a three-dimensional array, and 
so on. 

vax> VAX-/ / BASIC 

1 . The name of the routine can consist of from 1 to 31 characters and must conform to the 
following rules: 

• The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), periods (.), or underscores (_). 

• A quoted name can consist of any combination of printable ASCII characters. 

2. Routine can be a system service, an RTL routine, or any procedure written in a language 
that supports the VAX-) 1 Procedure Calling Standard. See BASIC on VAX/VMS Systems for 
more information on using system services, RTL routines, and other procedures. 

3. VAX-1 1 BASIC allows you to pass up to 255 parameters. 

4. You cannot pass virtual arrays. 
BP2) BASIC-PLUS-2 

1 . The name of the routine can consist of from one to six characters and must conform to the 
following rules: 

• The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), or periods (.). 

• A quoted name can consist of any combination of alphabetic characters, digits, dollar 
signs ($), periods (.), or spaces. 

2. Routine can be a BASIC-PLUS-2 subprogram or a subprogram written in another 
language. 

Note 

Although "you can call routines written in other languages, BASIC-PLUS-2 does 
not support calling anything but BASIC-PLUS-2 routines. 
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3. You can pass all arguments BY REF, but you can pass only string values and entire arrays 
BY DESC. 

4. BASIC-PLUS-2 lets you pass up to eight parameters to a BASIC-PLUS-2 subprogram and 
up to 255 parameters to a MACRO-1 1 subprogram. 

General Rules 

1. The optional pass-mech clauses tell BASIC how to pass arguments to the called sub- 
program. Table 19 describes VAX-11 BASIC parameter passing mechanisms. Table 20 
describes BASIC-PLUS-2 parameter passing mechanisms. 

• BY REF specifies that BASIC passes the argument's address. This is the default for all 
arguments except strings and entire arrays. 

• BY VALUE specifies that VAX-11 BASIC passes the argument's 32-bit value and that 
BASIC— PLUS— 2 passes the argument's 16-bit value. 

• BY DESC specifies that BASiC passes the address of a VAX-11 BASIC descriptor or a 
BASIC-PLUS-2 descriptor. For information about the format of a VAX-/ 1 BASIC descrip- 
tor for strings and arrays, see Appendix C in BASIC on VAX I VMS Systems; for informa- 
tion on other types of descriptors, see the VAX Architecture Handbook. BASIC-PLUS-2 
creates descriptors only for strings and arrays; these descriptors are described in Appen- 
dix C in BASIC on RSX-1 1M/M-PLUS Systems and BASIC on RSTS/E Systems. 

2. You can specify a null argument as an actual-param for non-BASIC routines by omitting 
the argument and the pass-mech, but not the commas or parentheses. This forces BASIC to 
pass a null argument as defined by your operating system and allows you to access system 
routines from BASIC. 

3. Arguments in the actual-param list must agree in data type and number with the formal 
parameters specified in the subprogram. 

4. An argument is modifiable when changes to it are evident in the calling program. Changing 
a modifiable parameter in a subprogram means the parameter is changed for the calling 
program as well. Variables and entire arrays passed BY DESC or BY REF are modifiable. 

5. An argument is nonmodifiable when changes to it are not evident in the calling program. 
Changing a nonmodifiable argument in a subprogram does not affect the value of that 
argument in the calling program. Arguments passed BY VALUE, constants, and expressions 
are nonmodifiable. Passing an argument as an expression (by placing it in parentheses) 
changes it from a modifiable to a nonmodifiable argument. 

6. For expressions and virtual array elements passed BY REF, BASIC makes a local copy of the 
value, and passes the address of this local copy. For dynamic string arrays, BASIC passes a 
descriptor of the array of string descriptors. BASIC passes the address of the argument's 
actual value for all other arguments passed BY REF. 

7. No files are closed when the CALL statement executes. 

VAX-1 1 BASIC <vax) 

1 . Only BYTE, WORD, LONG, and SINGLE values can be passed by BY VALUE. BYTE and 
WORD values passed by VALUE are converted to LONG values. 
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BASIC-PLUS-2 

1 Onlv BYTE anW WORD valu<=>c ran ho naccoH RV VA' I IP RVTP »/->i., P r ^ 2C o^^l DV V/AI I IC 

are converted to WORD values. 

2. BASIC-PLUS-2 does not allow recursion. That is, once a subprogram is called, it cannot 
be called again until the SUBEND or SUBEXIT statement has executed or until an error has 
been trapped with ON ERROR GO BACK. 

Examples 

200 CALL SUBl BY REF (EMPNAME*. (Z'Jf.) BY VALUE , D*(> BY DESC) 

Table 19: VAX-11 BASIC Parameter Passing Mechanisms 



Argument Type 


BY VALUE 


BY REF 


BY DESC 


Numeric Arguments 


Variables 


**YES 


*YES 


YES 


Constants 


**YES 


* Local copy 


Local copy 


Expressions 


**YES 


* Local copy 


Local copy 


Array elements 


**YES 


*YES 


YES 


Virtual array elements 


"YES 


* Local copy 


Local copy 


Entire arrays 


NO 


YES 


*YES 


Entire virtual arrays 


NO 


NO 


NO 


String Arguments 


Variables 


NO 


YES 


*YES 


Constants 


NO 


Local copy 


*Local copy 


Expressions 


NO 


Local copy 


*Local copy 


Array elements 


NO 


YES 


*YES 


Virtual array elements 


NO 


Local copy 


* Local copy 


Entire arrays 


NO 


YES 


*YES 


Entire virtual arrays 


NO 


NO 


NO 



One asterisk indicates the default parameter passing mechanisms for 
BASIC programs. 

Two asterisks indicate that the value can have 32 bits, at most. 
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Table 20: BASIC-PLUS-2 Parameter Passing Mechanisms 



Argument Type 


BY VALUE 


BYREF 


BY DESC 


Numeric Arguments 








Variables 


**YES 


*YES 


NO 


Constants 


**YES 


* Local copy 


NO 


Expressions 


**YES 


* Local copy 


NO 


Array elements 


**YES 


* Local copy 


NO 


Virtual array elements 


**YES 


* Local copy 


NO 


Entire arrays 


NO 


YES 


*YES 


Entire virtual arrays 


NO 


NO 


*YES 


String Arguments 


Variables 


NO 


YES 


*YES 


Constants 


NO 


Local copy 


*Local copy 


Expressions 


NO 


Local copy 


local copy 


Array elements 


NO 


Local copy 


*Local copy 


Virtual array elements 


NO 


Local copy 


*Local copy 


Entire arrays 


NO 


YES 


*YES 


Entire virtual arrays 


NO 


NO 


*YES 



One asterisk indicates the default parameter passing mechanisms for 
BASIC programs. You should never use a BY clause when calling a BASIC 
subprogram irorn a BAbiv~ main program. 

Two asterisks indicate that the value can be only WORD or BYTE. Other 
data types require more than the 16 bits of storage allowed. 



Note 

DIGITAL recommends that you not pass entire virtual arrays as parameters in the CALL 
statement. Instead, you can share the data in a virtual array between a calling program 
and a subprogram by opening a virtual file in either program and dimensioning the 
array (using the same channel number) in both programs. 
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2.0 CHAIN 



Note 



The CHAIN statement is not recommended for new program development. DIGITAL 
recommends that you use the CALL statement for program segmentation. 



Function 



The CHAIN statement transfers control from the current program to an executable BASIC program. 
CHAIN closes all files, then requests that the new program begin execution. Control does not return 
to the original program when the new program finishes executing. 



Format 



General 




CHAIN str- 


exp 


BASIC-PLUS-2 


on RSTS/E only 


CHAIN str- 


exp [ LINE lin-num ] 



Syntax Rules 



1 . Str-exp represents the file specification of the program to which control is passed. It can be 
a quoted or unquoted string. 



• Str-exp must refer to an executable image or BASIC signals an error. 

• If you do not specify a file type, VAX-// BASIC searches for an EXE file type and 
BASIC-PLUS-2 searches for a TSK file type. 

• You cannot chain to a program on another node. 
BASIC-PLUS-2 

(rsts) 1 . On RSTS/E systems you can specify that control pass to a specified line number in another 

v — y BASIC-PLUS-2 program. 

• Lin-num specifies a line in another BASIC program. It must be in the range 1 to 32767, 
inclusive. 

• If you specify a lin-num, the program to which control passes must have been compiled 
with the /CHAIN qualifier. The /CHAIN qualifier overrides the /NOLINE qualifier. 

General Rules 

1. Execution starts at the first line number of the specified program unless your system is 
RSTS/E and you have specified a lin-num at which execution is to start. 

(rsts) 2. On RSTS/E systems, BASIC-PLUS-2 signals an error when the specified line number does 

not exist. 
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d«4u^ ^u^ir^rr hI/dc niaro all artivo nutnut huffpr^ fpxrpnt terminal-format files) are 
written, all open files are closed, and all storage is released. On RSTS/E systems, the last 
buffer (512 bytes) of a terminal-format file does not get written unless the file is closed 
before the CHAIN statement executes. 

Because a CHAIN statement passes control from the executing image, the values of any 
program variables are lost. This means that you can pass parameters to a chained program 
only by using files or a system-specific feature such as the GET/PUT Core Common on 
RSTS/E systems, or LIB$GET and LIB$PUT on VMS systems. 

See BASIC on RSTS/E Systems or BASIC on RSX-1 1 M I M-PLUS Systems for information 
about how the CHAiN statement is implemented on your system. 



Examples 






Genera/ 






100 


CHAIN 


"PR0G2" 


900 


CHAIN 


PROGS, EKE 



BASIC-PLUS-2 on RSTS/E only 

200 CHAIN PROGA.TSK LINE 300 
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CHANGE 
3.0 CHANGE 

Function 



The CHANGE statement: 1 ) converts a string of characters to their ASCII integer values or 2) converts 
a list of numbers to a string of ASCII characters. converts 



Format 



String Variable to Array 

CHANGE str-exp TO num-array 
Array to String Variable 

CHANGE num-array TO str-vbl 



Syntax Rules 




1 ' ™2~% A a c K ,r h0Uld !f 3 ? ne : dimensional / rray (or list) - lf y° u s P ecif V a two-dimensional 
array, BASIC converts only the zero row of that array. BASIC does not support CHANGE to 
or from arrays of more than two dimensions. 

2. Str-exp is a string expression. 

Cvax> 3. VAX-1 1 BASIC does not support RECORD elements as a destination string or as a source 

or destination array for the CHANGE statement. 

Genera! Ruies 

String Variable to Array 
1 . This format converts each character in str-exp to its ASCII value. 

BASIC assigns the value of str-exp's length to the zero element (0) or (0,0) of the num-array. 

BASIC assigns the ASCII value of the first character in str-exp to the first element, (1) or 
0,1 , of num-array, the ASCII value of the second character to the second element (2) or 
(0,2), and so on. ' v ' 

4. If the string is longer than the bounds of num-array, BASIC does not translate the excess 
characters, and s.gnals the error "subscript out of range" (ERR = 55). Element zero, (0) or 
(0,0), of num-array still contains the length of str-exp. 

Array to String Variable 
1 . This format converts the elements of num-arr to a string of characters. 



2. 
3. 



2. 



The length of str-vbl is determined by the value in the zero element, (0) or (0 0) of 
num-array. If the value of element zero is greater than the array bounds, BASIC signals'the 
error "subscript out of range" (ERR = 55). B 
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3. BASIC changes the first element, (1) or (0,1), of num-array to its ASCII character equiva- 
lent, the second element, (2) or (0,2), to its ASCIi equivalent, and so on. The length of the 
returned string is determined by the value in the zero element of num-array. For example, 
if num-arr is dimensioned as (10), but the zero element (0) contains the value 5, BASIC 
changes only elements (1), (2), (3), (4), and (5) to string characters. 

4. BASIC truncates floating-point values to integers before converting them to characters. 

5. Values in array elements are treated modulo 256. 

Examples 

String Variable to Array 

50 DIM ARRAY_CHANGESX<6> 

GO CHANGE "ABCDE" TO ARRAY_CHANGESX 

Array to String Variable 

200 CHANGE ARRAY_CHANGES% TO A$ 
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4.0 CLOSE 

Function 

The CLOSE statement ends I/O processing to a device or file on the specified channel. 

Format 



CLOSE chnl-exp,, 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
can be preceded by an optional pound sign (#). 

General Rules 

1 . BASIC writes the contents of any active buffers to the file or device before it closes that file 
or device. 

2. Channel (the controlling terminal) cannot be closed. An attempt to do so has no effect. 

3. If you close a magnetic tape file that is open FOR OUTPUT, BASIC writes an end-of-file on 
the magnetic tape. 

4. If you try to close a channel that is not currently open, BASIC does not signal an error and 
the CLOSE statement has no effect. 

Examples 

1000 CLOSE *1 , 3 
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Function 



The COMMON statement defines a named, shared storage area called a COMMON block or pro- 
gram section (PSECT). BASIC program modules can access the values stored in the COMMON by 
specifying a COMMON with the same name. 

Format 





COM 






COMMON 


[ ( com-nam ) ] { [ data-type ] com-item },... 


corn-item: 


num-unsubs-vbl-nam 
•num-array-nam ( int-const,... ) 
str-unsubs-vbl-nam = int-const 




i 


str-array-nam ( int-const,... ) [ = int-const ] ► 




FILL [ ( int-const ) ][ = int-const ] 






FILL% [ ( int-const ) ] 






FILL$ [ ( int-const ) ] [ = int-const ] 





Syntax Rules 

1 . Com-nam is optional. If present, it must be in parentheses. 

2. A COMMON can have the same name as a program variable. However, in 
BASIC- PLUS- 2 , a COMMON cannot have the same name as a subprogram within the 
same task image. 

3. A COMMON and a MAP in the same program module cannot have the same name. 

4. Com-item declares the name and format of the data to be stored. 

• Num-unsubs-vbl-nam and num-arr-nam specify a numeric variable or a numeric array. 

• Str-unsubs-vbl-nam and str-arr-nam specify a fixed-length string variable or array. You 
can specify the number of bytes to be reserved for the variable with the -int-const 
clause. The default string length is 16. 

• The FILL, FILL%, and FILLS keywords allow you to reserve parts of the record buffer 
within or between data elements and to define the format of the storage. Int-const speci- 
fies the number of FILL items to be reserved. The -int-const clause allows you to specify 
the number of bytes to be reserved for string FILL items. Table 21 describes FILL item 
format and storage allocation. 
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Note 

in the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n) represents n elements, not n + 1 . 

5. Data-type can be any BASIC data-type keyword or, in VAX-/ 7 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 

6. When you specify a data-type, all following corn-items, including FILL items, are of that 
data type until you specify a new data type. 

7. If you do not specify any data-type, corn-items take the current default data type and size. 

8. Variable names, array names, and FILL items following a data-type cannot end in a dollar 
sign or percent sign character. 

9. Variables and arrays declared in a COMMON statement cannot be declared elsewhere in 
the program by any other declarative statements. 

10. COMMON elements must be separated with commas. 

Cvax> VAX-11 BASIC 

1 . The default com-nam is "$BLANK". 

2. Com-nam can consist of from 1 to 31 characters. The first character of the name must be 
an alphabetic character (A through Z). The remaining characters, if present, can be any 
combination of letters, digits (0 through 9), dollar signs ($), periods (.), or underscores (_). 

(BP2) BASIC-PLUS-2 

1 . The default com-nam is ".$$$$.". 

2. Com-nam can consist of from one to six characters. The first character must be an alpha- 
betic character (A through Z). The remaining characters, if present, can be any combina- 
tion of letters, digits (0 through 9), dollar signs ($), or periods (.). 
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Table 21 : FILL Item Formats and Storage Allocations 



FILL Format 


Storage Allocation 


FILL 

FILL(int-const) 

FILL% 

FILL%(int-const) 

FILL$ 

FILL$(int-const) 

FILLS = int-const 

FILL$(int-const) = int-const 


Allocates storage for one floating-point element unless preceded by a data-type; the 
number of bytes allocated depends on the default floating-point data size or the speci- 
fied data-type. 

Allocates storage for the number of floating-point elements specified by int-const unless 
preceded by a data-type; the number of bytes allocated for each element depends on the 

A~£~..U£i — .«.: :-,* ,J~*~ ,-:-.« «- tU~ -««^.:£: — 1 ,J~*~ *.,«« 

UCldUlL lluaung-|Jl'llll Udld 3iZc \ji Liic ap&i-iiicu uaui-type. 

Allocates storage for one integer element; the number of bytes allocated depends on the 
default integer size. 

Allocates storage for the number of integer elements specified by int-const; the number 
of bytes allocated for each element depends on the default integer size. 

Allocates 16 bytes of storage for a string element. The dollar sign can be omitted if the 
FILL keyword is preceded by the STRING data-type. 

Allocates 16 bytes of storage for the number of string elements specified by int-const 
The dollar sign can be omitted if the FILL keyword is preceded by the STRING data-type. 

Allocates the number of bytes of storage specified by = int-const for a string element. 
The dollar sign can be omitted if the FILL keyword is preceded by the STRING data-type. 

Allocates the number of bytes of storage specified by = int-const for the number of string 
elements specified by int-const. The dollar sign can be omitted if the FILL keyword is 
preceded by the STRING data-type. 



Note 

In the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n) represents n elements, not n + 1 . 



General Rules 



1. A COMMON area and a MAP area with the same name, in different program modules, 
specify the same storage area. 

2. BASIC does not execute COMMON statements. The COMMON statement allocates and 
defines the data storage area at compile time. 

3. When you link or task-build your program, the size of the COMMON area is the size of the 
largest COMMON area with that name. That is, BASIC concatenates COMMON state- 
ments with the same com-nam within a single program module into a single PSECT. The 
total space allocated is the sum of the space allocated in the concatenated COMMON 
statements. 

4. The COMMON statement must lexically precede any reference to variables declared in it. 

5. A COMMON area can be accessed by more than one program module, as long as you 
define the com-nam in each module that references the COMMON. 
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6. Variable names in a COMMON statement in one program module need not match those in 
another program module. 

7. VAX-1 1 BASIC does not initialize variables in COMMON blocks. 

8. Since BASIC-PLUS-2 initializes variables in COMMON blocks, you must use unique 
names for each variable in each COMMON block. 

BP2) 9. In BASIC-PLUS-2, you should know how your program overlays if data stored in a 

COMMON area is to be shared by several program modules. The COMMON should be 
named in an overlay unit that will remain in memory as long as program units need to 
reference the COMMON data. If the overlay that names the COMMON is forced out of 
memory, BASIC reinitializes the COMMON area to zero when the overlay is brought back 
into memory. See BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E Systems for 
information on overlay structures. 

10. The data-type specified for corn-items or the default data type and size determines the 
amount of storage reserved in a COMMON block: 

• BYTE integers reserve 1 byte. 

• WORD integers reserve 2 bytes. 

• LONG integers reserve 4 bytes. 

• SINGLE floating-point numbers reserve 4 bytes. 

• DOUBLE floating-point numbers reserve 8 bytes. 

• GFLOAT floating-point numbers reserve 8 bytes (VAX-1 1 BASIC only). 

• HFLOAT floating-point numbers reserve 16 bytes (VAX-1 1 BASIC only). 

• DECIMAL(d,s) packed decimal numbers reserve (d + 1)/2 bytes (VAX-1 1 BASIC only). 

• STRING reserves 16 bytes (the default) or the number of bytes you specify with 
= int-const. 

Examples 

500 COMMON (INYEN) INTEGER SHELF.NUMBER t STRING ROW = 2, & 
DOUBLE FILL) PART.BIN, LIST.PRICE 
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fi.O DATA 

Function 

The DATA statement creates a data block for the READ statement. 

Format 





num-lit 




DATA 


str-lit 
unq-str 





Syntax Rules 

1. Num-lit specifies a numeric literal. 

2. Str-lit is a character string that starts and ends with double or single quotation marks. The 
quotation marks must match. 

3. Unq-str is a character sequence that does not start and end with double or single quotation 
marks and does not contain a comma. 

4. Commas separate data elements. If a comma is part of a data item, the entire item must be 
enclosed in quotation marks. 

5. Because BASIC treats comment fields in DATA statements as part of the DATA sequence, 
do not include comments. 

6. A DATA statement must be the last or the only statement on a line. 

L_/y~V | r\ bLCUd 1 Id 1 lb lliubl CN IVJ Willi d. liiifc: lci 1 1 in iolui . LJf\Ji\~ iiilci^iuu an v_i id! CIv-lCi j C/vv-v^|js. 

the ampersand (&) between the keyword DATA and the final line terminator as part of the 
data. You can continue DATA statements by placing an ampersand (&) immediately before 
the line terminator. 

8. You cannot use the percent sign suffix for integer constants that appear in DATA state- 
ments. An attempt to do so causes BASIC to signal "Data format error" (ERR = 50) when 
you try to run the program. 

General Rules 

1 . DATA statements are local to a program module. 

2. BASIC does not execute DATA statements. Instead, BASIC passes control to the next exe- 
cutable statement. 

3. A program can have more than one DATA statement. BASIC assembles data from all DATA 
statements in a single program unit into a lexically ordered single data block. 

4. BASIC ignores leading and trailing blanks and tabs unless they are in a string literal. 
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5. Commas are the only valid data delimiters. You must use a quoted string literal if the 
comma is to be part of a string. 

6. BASIC ignores DATA statements without an accompanying READ statement. 

7. BASIC signals the error "Data format error" if the DATA item does not match the data type 
of the variable specified in the READ statement or if a data element that is to be read into 
an integer variable ends with a percent sign (%). If a string data element ends with a dollar 
sign ($), BASIC treats the dollar sign as part of the string. 

Examples 

300 DATA 35. 32.3. PRODUCTION SEQUENCE. 'SYSTEM'. '1,2' 



144 BASIC Reference Manual 



DECLARE 



7 n ncn adp 

Function 

The DECLARE statement explicitly assigns a data type to and names a variable, an entire array, a 
function, or a constant. 

Format 



Variables 




DECLARE data-type decl-item [, [ data-type ] decl-item ]... 




DEF Functions 




DECLARE data-type FUNCTION { def-nam [ ( [ def-param ],.. 


• ) ] },.- 


Named Constants 




DECLARE data-type CONSTANT { const-nam = const },... 




decl-item: 


unsubs-vbl-nam 
array-nam ( int-const,... ) 






def-param: [ data-type ] 





Syntax Rules 

1 . Data-type can be any BASIC data-type keyword or, in VAX-1 1 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 

Variables 

1 . Decl-item names a variable or an array. 

2. A decl-item cannot end in a percent sign (%) or dollar sign ($). 

3 A decl-item named in a DECLARE statement cannot also be named in another DECLARE 
statement, or a DEF, EXTERNAL, FUNCTION, SUB, COMMON, MAP, or DIM statement. 

4. Int-const specifies the upper bounds of the array-nam. 

5. Each decl-item is associated with the preceding data-type. A data-type is required for the 
first decl-item. 

6. Decl-items of data-type STRING are dynamic strings. 
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DEF Functions 



1 



~e.-nam names t,.e DEF function. It cannot end with a percent sign (%) or doiiar sign ($). 

2. Data-type specifies the data type of the value the function returns. 

3. Def-params specify the number and, optionally, the data-type of the DEF parameters 
Parameters define the arguments the DEF expects to receive when invoked. 

• When you specify a data-type, all following parameters are of that data type until you 
specify a new data type. 

• If you do not specify any data-type, parameters take the current default data type and 
size. 

• The number of parameters equals the number of commas plus one. For example, empty 
parentheses specify one parameter of the default type and size; one comma inside the 
parentheses specifies two parameters of the default type and size, and so on. One 
data-type inside the parentheses specifies one parameter of the specified data type; two 
data-types separated by one comma specifies two parameters of the specified type' and 
so on. 

Named Constants 

1 . Const-nam is the name you assign to the const. 

2. Data-type specifies the data type of the const-nam. The value of the const must be numeric 
if the data type is numeric and string if the data type is STRING. If the data-type is STRING, 
const must be a quoted string or another string constant. 

3. Const cannot end with a percent sign (%) or a dollar sign ($). 

4. Const cannot be of the RFA data type. 

5. For VAX-1 1 BASIC, string constants cannot exceed 498 characters. 

6. For BASIC-PLUS-2, string constants cannot exceed 128 characters. 

7. VAX-1 1 BASIC allows const to be an expression for all data types except DECIMAL. 
Expressions are not allowed as values when you name DECIMAL constants. 

8. BASIC-PLUS-2 allows const to be an expression for STRING and INTEGER data types. 
Expressions are not allowed as values when you name floating-point constants. 

9. Allowable operators in DECLARE CONSTANT expressions include all valid arithmetic, 
relational, and logical operators except exponentiation. Built-in functions cannot be used in 
DECLARE CONSTANT expressions. The following examples use valid expressions as 
values: 

100 DECLARE DOUBLE CONSTANT MAX.UALUE = (PI / Z) iVAX-1 1 BASIC only) 
100 DECLARE STRING CONSTANT LEFT. ARROW = ('< ' + |_F + CR) 
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1 . The DECLARE statement is not executable. 

2. The DECLARE statement must lexically precede any reference to the variables, functions, 
or constants named in it. 

3. You cannot declare virtual arrays. 

4. To avoid confusion and to retain BASIC'S implicit data typing feature, variable names 
ending with a dollar sign or percent sign are invalid in a DECLARE statement. 

Variables 

1 . Variables named in a DECLARE statement are initialized to zero if numeric or to the null 
string if string. 

2. Subsequent decl-items are associated with the specified data type until you specify another 
data-type. 

DEF Functions 

1 The DECLARE FUNCTION statement allows you to name a function defined in a DEF 
statement, specify the data type of the value the function returns, and declare the number 
and data type of the DEF parameters. 

2. Data-type keywords must be separated by commas. For example: 

100 DECLARE DOUBLE FUNCTION INTEREST i> .DOUBLE »SINGLE ) 

This example decares two parameters of the default type and size, one DOUBLE parame- 
ter, and one SINGLE parameter for the function named INTEREST. 

3. The first specification of a def-param is the default for subsequent arguments until you 
specify another def-param. 

Named Constants 

1. The DECLARE CONSTANT statement allows you to name a constant value and assign a 
data type to that value. Note that you can specify only one data type in a DECLARE 
CONSTANT statement. To declare another constant, you must use a second DECLARE 
CONSTANT statement. 

2. You cannot change the value assigned to const-nam. 

3. You cannot use a const-nam where a variable is required. 
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4. In VAX-1 1 BASIC, the specified data-type determines the data type of const. For example: <vax> 

100 DFTI flPF unon rnucTAiiT mmm _ < cr n/ 



100 DECLARE WORD CONSTANT MMM =1,5 

200 DECLARE REAL CONSTANT ZZZ = 123X 

300 DECLARE BYTE CONSTANT YYY = '123'L 

400 PRINT MMM, ZZZ ,YYY 



RUNNH 



123 123 



In this example, BASIC truncates the value 1 .5 to a WORD integer, and ignores the percent 
suffix and the L (LONG) data type. ' 

5. BASIC-PLUS-2 signals the error "Constant is inconsistent with the type of <name> " if the (bk) 
data type of const does not match the specified data-type. 



Note 

Data types specified in a DECLARE statement override any defaults specified in 
COMPILE command qualifiers or OPTION statements. 

Examples 

Variables 

100 DECLARE INTEGER CATALOG. NUM , DOUBLE PRICE, STRING ITEM. NAME 

DEF Functions 

100 DECLARE INTEGER FUNCTION AMOUNT (, .DOUBLE ,BYTE ,* ) 

Named Constants 

100 DECLARE DOUBLE CONSTANT INTEREST.RATE = 15,22 
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8.0 DEF 

Function 

The DEF statement lets you define a single- or multi-line function. 

Format 



Single-Line DEF 






DEF [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vb!-nam ],.. 


\ l = 

" / J 


= exp 


Multi-Line DEF 






DEF [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vbl-nam ],.. 


• ) ] 




[ statement ]... 






j END DEF J 






( FNEND ) 







Syntax Rules 



1 . Data-type can be any BASIC data-type keyword or, in VAX-1 1 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 

2. The data-type that precedes the def-nam specifies the data type of the value returned by the 
DEF function. 

3. Def-nam is the name of the DEF function. The def-nam may contain from 1 to 31 
characters. 

4. If the def-nam also appears in a DECLARE FUNCTION statement, the following rules 
apply: 

• A function data-type is required. 

• The first character of the def-nam must be an alphabetic character (A through Z). The 
remaining characters may be any combination of letters, digits (0 through 9), dollar signs 
($), underscores (_), or periods (.), with one restriction: the last character cannot be a 
dollar sign. 

5. If the def-nam does not appear in a DECLARE FUNCTION statement, but the DEF state- 
ment appears before the first reference to the def-nam, the following rules apply: 

• The function data-type is optional. 

• The first character of the def-nam must be an alphabetic letter (A through Z). The remain- 
ing characters can be any combination of letters, digits, dollar signs, underscores, or 

periods. (continued on next page) 
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• If a function data-type is specified, the last character in the def-nam cannot be a dollar 
sign or percent sign. 

• If a function data-type is not specified, the last character in the def-nam must be a 
percent sign (%) for an INTEGER function, a dollar sign ($) for a STRING function, or a 
letter, digit, period, or underscore for a function of the default type and size. 

6. If the def-nam does not appear in a DECLARE FUNCTION statement, and the DEF state- 
ment appears after the first reference to the def-nam, the following rules apply: 

• The function data-type cannot be present. 

• The first two characters of the def-nam must be FN. The remaining characters can be any 
combination of letters, digits, dollar signs, underscores, or periods, with one restriction: 
the last character must be a percent sign {%) for an INTEGER function, a dollar sign ($) 
for a STRING function, or a letter, digit, period, or underscore for a function of the 
default type and size. 

• There must be at least one character between the FN characters and the ending dollar 
sign or percent character. FN$ and FN% are not valid function names. 

7. Unsubs-vbl-nam specifies optional formal DEF parameters. Because the parameters are 
local to the DEF function, any reference to these variables outside the DEF body creates a 
different variable. 

8. You can specify the data-type of DEF parameters with a data-type keyword or, in VAX-1 1 
BASIC, with a data type defined in a RECORD statement. If you do not include a data type, 
the parameters are of the default type and size. Parameters that follow a data-type keyword 
are of the specified type and size until you specify another data type. 

9. BASIC-PLUS-2 allows you to specify up to eight parameters in a DEF statement. 

10. VAX-1 1 BASIC allows you to specify up to 255 parameters in a DEF statement. 

Single-Line DEF 
1 . Exp specifies the operations the function performs. 

Multi-Line DEF 

1 . Statements specify the operations the function performs. 

2. The END DEF or FNEND statement is required to end a multi-line DEF. 

3. You can use any BASIC statement except END FUNCTION, END SUB, FUNCTION, 
FUNCTIONEND, FUNCTIONEXIT, DEF, or DEF* in a function definition. 
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1 . When BASIC encounters a DEF statement, control of the program passes to the next exe- 
cutable statement after the DEF. 

2. Functions are invoked when you use the function name in an expression. 

3. You cannot specify how parameters are passed. When you invoke a function, BASIC 
evaluates parameters from left to right and passes parameters to the function so that they 

„_^„i !__ ._J:.c: I Ki.. m n,;,- r>ii-.mntpi-c tko niccQfl RV V A I I IF aruA ctrina naramptpr? arp 

Cannot De mOUliieu. ixumcui. ^iai qi i icici b di^ pdSSv.v-1 u i v/~v._>_>i- uiiu 3t.... D ,_w.. «..._*. — ■ — *- 

passed BY DESC, where the descriptor points to a local copy. DEF functions may reference 
variables in the main program, but they cannot reference variables in other DEF or DEF* 
functions. A DEF function may, therefore, modify other variables in the program, but not 
variables within another DEF function. 

4. A DEF is local to the program or subprogram that defines it. 

5 The DEF statement, or the first invocation of a function, whichever occurs first, constitutes 
the declaration of the function. The DECLARE FUNCTION statement defines the name of 
the function, but does not invoke it. 

6. If your program invokes a function with a name that does not start with FN before the DEF 
statement defines the function, or if the number of parameters, types of parameters, or type 
of result declared in the invocation disagree with the number or types of parameters 
defined in the DEF statement, BASIC signals an error. 

7. DATA statements in a multi-line DEF are not local to the function; they are local to the 
program module containing the function definition. 

8. The function value (that is, the location storing the value the function returns) is initialized 
to zero or the null string each time you invoke the function. 

9. ON ERROR GO BACK is the default error handler in a DEF function definition. 

10. ON ERROR statements within a DEF are local to the function. 

11. A GOTO, GOSUB, ON ERROR GOTO, or RESUME statement in a multi-line function 
definition must refer to a line number or label in the same function definition. 

12. You cannot transfer control into a multi-line DEF except by invoking the function. 

13. DEF functions can be recursive. 
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Examples 

Single-Line DEF 

1000 DEF DOUBLE ADD (DOUBLE ft, B, SINGLE C»D»E> = A + B + C + D + E 
2000 INPUT 'Enter five numbers to be added ' 5 V »W ,X »Y iZ 
2010 PRINT 'The sum i s ' 5 ADD ( V ,W »X , Y ,Z ) 

Multi-Line DEF 

1000 DEF DOUBLE PAYROLL < INTEGER HOURS, REAL RATE) 
EXIT DEF IF HOURS = 
DECLARE INTEGER OVERTIME 
OVERTIME = HOURS - 40 
IF OVERTIME <= 

THEN HOURS = HOURS 

ELSE HOURS = 40 
END IF 

DECLARE REAL CONSTANT OVER_RATE =1,5 

PAYROLL = (HOURS * RATE) + (OVERTIME * (OVER RATE * RATE)) 
1030 END DEF " Hlt " 

1040 INPUT "Your hours this wee k " !MY_HOURS 

1045 INPUT "Your pay rat e " 5MY_PAY_RATE 

1050 PRINT 'Your Pay for the weeK i s ", PAYROLL ( MY.HOURS ,MY_PAY_RATE ) 
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9.0 DEF* 

Function 

The DEF* statement lets you define a single- or multi-line function. 

Note 

The DEF* statement is not recommended for new program development. DIGITAL 
recommends that you use the DEF statement for defining single- and multi-line 
functions. 



Format 



Single-Line DEF* 






DEF* [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vbl-nam ],.. 


■ )] = 


= exp 


Multi-Line DEF* 






DEF* [ data-type ] def-nam [ ( [ [ data-type ] unsubs-vbl-nam ],. 


■ )] 




[ statement ]... 








END DEF 










FNEND 









Syntax Rules 



1 . Data-type can be any BASIC data-type keyword or, in VAX-1 1 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 

2. The data-type that precedes the def-nam specifies the data type of the value returned by the 
DEF* function. 

3. Def-nam is the name of the DEF* function. The def-nam may contain from 1 to 31 
characters. 

4. If the def-nam also appears in a DECLARE FUNCTION statement, the following rules 
apply: 

• A function data-type is required. 

• The first character of the def-nam must be an alphabetic character (A through Z). The 
remaining characters may be any combination of letters, digits (0 through 9), dollar signs 
($), underscores (_), or periods (.), with one restriction: the last character cannot be a 
dollar sign. 
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5. If the def-nam does not appear in a DECLARE FUNCTION statement, but the DEF* state- 
ment appears before the first reference to the def-nam, the following rules apply: 

• The function data-type is optional. 

• The first character of the def-nam must be an alphabetic letter (A through Z). The remain- 
ing characters can be any combination of letters, digits, dollar signs, underscores, or 
periods. 

• If a function data-type is specified, the last character in the def-nam cannot be a dollar 
sign or a percent sign. 

• If a function data-type is not specified, the last character in the def-nam must be a 
percent sign (%) for an INTEGER function, a dollar sign ($) for a STRING function, or a 
letter, digit, period, or underscore for a function of the default type and size. 

6. If the def-nam does not appear in a DECLARE FUNCTION statement, and the DEF* state- 
ment appears after the first reference to the def-nam, the following rules apply: 

• The function data-type cannot be present. 

• The first two characters of the def-nam must be FN. The remaining characters can be any 
combination of letters, digits, dollar signs, underscores, or periods, with one restriction: 
the last character must be a percent sign (%) for an INTEGER function, a dollar sign ($) 
for a STRING function, or a letter, digit, period, or underscore for a function of the 
default type and size. 

• There must be at least one character between the FN characters and the ending dollar 
sign or percent character. FN$ and FN% are not valid function names. 

7. Unsubs-vbl-nam specifies optional formal function parameters. 

8. You can specify the data-type of function parameters with a data-type keyword. If you do 
not specify a data-type, parameters are of the default type and size. Parameters that follow 
a data-type keyword are of the specified type and size until you specify another data-type. 

9. BASIC-PLUS-2 allows you to specify up to eight parameters in a DEF* statement. 
10. VAX-1 1 BASIC allows you to specify up to 255 parameters in a DEF* statement. 
Single-Line DEF* 

1 . Exp specifies the operations the function performs. 
Multi-Line DEF* 

1 . Statements specify the operations the function performs. 

2. The END DEF or FNEND statement is required to end a multi-line DEF*. 

3. You can use any BASIC statement except END FUNCTION, END SUB, FUNCTION, 
FUNCTIONEND, FUNCTIONEXIT, DEF, or DEF* in a function definition. 
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General Ruies 



1. When BASIC encounters a DEF* statement, control of the program passes to the next 
executable statement after the DEF. 

2. Functions are invoked when you use the function name in an expression. 

3. You cannot specify how parameters are passed. When you invoke a DEF* function, 
BASIC evaluates parameters from left to right and passes parameters to the function so that 
they cannot be modified. Numeric parameters are passed BY VALUE, and string 

— ..~,~,~(.^.. c ~,r- P ^occq^ RV nFQ(~ \A/hpre> thp rlpKrrintnr noints tn a local COOV. DEF* 

functions may reference variables in the main program, but they cannot reference 
variables in other DEF or DEF* functions. A DEF* function may, therefore, modify varia- 
bles in the program, but not variables within another DEF* function. 

4. A DEF* is local to the program or subprogram that defines it. 

5. The DEF* statement permits inclusion of the GOTO, ON GOTO, GOSUB, and 
ON GOSUB statements in a multi-line DEF* function. This allows you to transfer pro- 
gram control outside the function definition. 

6. Although other variables used within the body of a DEF* are not local to the DEF*, DEF* 
formal parameters are. However, if you change the value of formal parameters within a 
DEF* function and then transfer control out of the DEF* without executing the END DEF 
or FNEND statement, variables outside the DEF* that have the same names as DEF* 
formal parameters are also changed. 

7. The DEF* statement, or the first invocation of a function, whichever occurs first, consti- 
tutes the declaration of the function. The DECLARE FUNCTION statement defines the 
name of the function, but does not invoke it. 

8. If your program invokes a function before the DEF* statement defines the function, or if 
the number of parameters, types of parameters, or type of result declared in the invoca- 
tion disagree with the number or types of parameters defined in the DEF* statement, 
BASIC signals an error. 

9. DEF* function values are not initialized when DEF* functions are invoked. Therefore, if a 
DEF* is invoked, and no new function value is assigned, the DEF* returns the value of its 
previous invocation. 

10. DEF* functions can be recursive. 

1 1 . DATA statements in a multi-line DEF* are not local to the function; they are local to the 
program module containing the function definition. 

12. The error handler of the program module that contains the DEF* is the default error 
handler for a DEF* function, not ON ERROR GO BACK as in DEF functions. Parameters 
return to their original values when control passes to the error handler. 
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Examples 

Single-Line DEF* 

1000 DEF* STRING CONCAT C STRING A,B> = A + B 
2000 INPUT 'Enter two wo rds ' 5W0RD1 »W0RD2 
2010 PRINT C0NCAT(W0RD1 ,W0RD2) 

Multi-Line DEF* 

1000 DEF* DOUBLE EXAMPLE ( DOUBLE At B. SINGLE C, D» E) 

EXIT DEF IF B = 

EXAMPLE = (A/B) + C - (DE) 
1030 END DEF 

1040 INPUT 'Enter 5 numbe rs ' 5V ,W »X , Y >Z 
1050 PRINT EXAMPLES, W,X»Y»Z) 
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10.0 DELETE 

Function 

The DELETE statement removes a record from a relative or indexed file. 

Format 



DELETE chnl-exp 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. !t 
must be immediately preceded by a pound sign (#). 

General Rules 

1 . The DELETE statement removes the current record from a file. You cannot then access the 
record. 

2. The file specified by chnl-exp must be open with ACCESS MODIFY or WRITE. 

3. You can delete a record only if the last I/O statement executed on the specified channel 
was a successful GET or FIND. 

4. The DELETE statement leaves the Current Record Pointer undefined and the Next Record 
Pointer unchanged. 

5. BASIC signals an error when the I /O channel is illegal or not open, when no current record 
exists, when access is illegal or illogical, when the operation is illegal, or when the record 
or bucket is locked. 

6. In VAX-1 1 BASIC, if the record being deleted is in a file opened with UNLOCK EXPLICIT, <vax) 
the DELETE statement does not remove the lock on the record. If no lock was imposed with 
a previous GET or FIND statement, the default lock, ALLOW NONE, remains imposed. 
The lock can be removed with the FREE or UNLOCK statement. See the sections on GET, 
FIND, OPEN, FREE, and UNLOCK in this manual for more information on explicit record 
locking and unlocking. 

Examples 

1000 DELETE 5 
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11.0 DIMENSION 



Function 



The DIMENSION statement creates and names a static, dynamic, or virtual array. The array subscripts 
determine the dimensions and size of the array. You can specify the data type of the array and 
associate the array with an I/O channel. 



Format 



Nonvirtual, Nonexecutable 



DIM 
DIMENSION 



Virtual 



DIM 
DIMENSION 



Executable 



DIM 
DIMENSION 



{ [ data-type ] array-nam ( int-const,... ) },... 



chnl-exp, { [ data-type ] array-nam ( int-const,... ) [ = int-const ] },. 



{ [ data-type ] array-nam { int-vbl,... ) },. 



Syntax Rules 



1 . Array-nam is an array name. It must conform to the rules for naming variables. 

2. An array-nam in a DIM statement cannot also appear in a COMMON, MAP, or DECLARE 
statement. 

3. Data-type can be any BASIC data-type keyword or, in VAX- 7 1 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 

4. If you do not specify a data type, the array-nam determines the type of data the array holds. 
If the array-nam ends in a percent sign (%), the array stores integer data. If the array-nam 
ends in a dollar sign ($), the array stores string data. Otherwise, the array stores data of the 
default type and size. 

5. A VAX-1 1 BASIC array can have up to 32 dimensions. 

6. A BASIC-PLUS-2 array can have up to eight dimensions. 
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7. Each instance of int-const or int-vbl within the parentheses specifies the upper bound of an 
array dimension. 

• In VAX-1 1 BASIC, array bounds must be in the range to 2 31 " 1 . 

• In BASIC-PLUS-2, array bounds must be in the range to 2 15_1 . 

• Although the compiler does not generate an error for subscript values outside of these 
ranges, there is a limit to the amount of storage your system can allocate. Therefore, very 
large arrays can cause an internal allocation error or a run-time error. 

Nonvirtual, Nonexecutable 

1. When all the dimension specifications are int-consts, as in DIM A(15%,10%,20%), the 
DIM statement is nonexecutable and the array is static. A static array cannot appear in 
another DIM statement because BASIC allocates storage at compile time. 

2. A nonexecutable DIM statement must lexically precede any reference to the array it dimen- 
sions. That is, you must DIMENSION a static array before you can reference array 
elements. 

Virtual 

1. The pound sign (#) must precede chnl-exp when dimensioning virtual arrays. 

2. The virtual array must be dimensioned and the file must be open before you can reference 
the array. 

3. When the data-type is STRING, the = int-const clause specifies the length of each array 
element. The default string length is 16 characters. Virtual string array lengths are rounded 
to the next higher power of two. 

Executable 

1. When any of the dimension specifications are int-vbls, as in DIM A(10%,20%,Y%), the 
DIM statement is executable and the array is dynamic. A dynamic array can be redimen- 
sioned with a DIM statement any number of times, since BASIC allocates storage at run 
time. 

General Rules 

1. You can create an array implicitly by referencing an array element without using a DIM 
statement. This causes BASIC to create an array with dimensions of (10), (10,10), 
(10,10,10), and so on, depending on the number of bounds specifications in the refer- 
enced array element. You cannot create virtual or executable arrays implicitly. 

2. The lower bound of a BASIC array is always zero, rather than one. Thus, A(1 0) allocates 1 1 
elements, A(10,10) allocates 121 elements, and A(0,0,0) allocates 1 element. 

3. BASIC allocates storage for arrays by row, from right to left. 
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Nonvirtual, Nonexecutable 



1. You can declarp arravc with thp rnuunw mad ->r.^ ncn adc ^ t , + „^,^ — »., a—.,.,.- c ~ 
declared cannot be redimensioned with the DIM statement. Furthermore, string arrays 
declared with a COMMON or MAP statement are always fixed-length. 

2. If you reference an array element declared in an array whose subscripts are larger than the 
bounds specified in the DIM statement, BASIC signals the error "Subscript out of ranee" 
(ERR = 55). 

Virtual 

1. When the rightmost subscript varies faster than the subscripts to the left, fewer disk 
accesses are necessary to access array elements in virtual arrays. 

2. Using the same DIM statement for multiple virtual arrays allocates all arrays in a single disk 
file. The arrays are stored in the order they were declared. 

3. Any program or subprogram can access a virtual array by declaring it in a virtual 
DIMENSION statement. For example: 

100 DIM #1 » A(10) 

200 DIM *1 t B(10> 

In this example, array B overlays array A. You must, however, specify the same channel 
number, data types, and limits in the same order as they occur in the DIM statement that 
created the virtual array. 

4. BASIC stores a string in a virtual array by padding it with trailing nulls to the length of the 
array element. It removes these nulls when it retrieves the string from the virtual array. 

5. In BASIC-PLUS-2 on RSX-1 1M/M-PLUS systems and in VAX-/ 1 BASIC, the OPEN state- 
ment for a virtual array must include the ORGANIZATION VIRTUAL clause for the 
chnl-exp specified in the DIMENSION statement. 

6. BASIC does not initialize virtual arrays and treats them as statically allocated arrays. You 
cannot redimension virtual arrays. 

7. Refer to the BASIC User's Guide for more information on virtual arrays. 
Executable 

1 . You create an executable, dynamic array by using integer variables for array bounds as in 
DIM A(Y%,X%). This eliminates the need to dimension an array to its largest possible size. 
Array bounds in an executable DIM statement can be constants or variables, but not 
expressions. At least one bound must be a variable. 

2. You cannot reference an array named in an executable DIM statement until after the DIM 
statement executes. 

3. You can redimension a dynamic array to make the bounds of each dimension larger or 
smaller, but you cannot change the number of dimensions. That is, you cannot redimen- 
sion a four-dimensional array to be a five-dimensional array. 
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4. The executable DIM statement cannot be used to dimension virtual arrays, arrays feceived 
as formal parameters, or arrays declared in COMMON, MAP, or nonexecutable DIM 
statements. 

5. An executable DIM statement always reinitializes the array to zero (for numeric arrays) or 
the null string (for string arrays). 

6. If you reference an array element declared in an executable DIM statement whose sub-, 
scripts are larger than the bounds specified in the last execution of the DIM, BASIC signals 
the error "Subscript out of range" (ERR = 55). 

Examples 

Nonvirtual, Nonexecutable 

300 DIM STRING NAME-LIST ( 100 > 100 ) , BYTE AGE(IOO) 

Virtual 

100 DIM *l%t STRING NAM_LIST ( 500 ) » REAL AMOUNT ( 10 . 10 ) 

Executable 

200 DIM DOUBLE INVENTORY < BASE .MARKUP ) 
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12.0 END 

Function 

The END statement marks the physical and logical end of a main program, a program module, or a 
block of statements. 

Format 



END [ block ] 




fDEF ^ 






FUNCTION 






GROUP 


(VAX-11 only) 


block: < 


IF 

RECORD (VAX-11 only) 




SELECT 






SUB 






^ VARIANT > 


(VAX-11 only) 



Syntax Rules 



1. 

2. 



The END statement with no block keyword marks the end of a main program. The END 
statement must be the last statement on the lexically last line in the main program. 

The END statement followed by a block keyword marks the end of a BASIC SUB or 
FUNCTION subprogram, or a DEF, IF, or SELECT statement block. In VAX-1 1 BASIC, END 
RECORD, END GROUP, and END VARIANT mark the end of a RECORD statement, or a 
GROUP component or VARIANT component of a RECORD statement. 

The END block statement must be the lexically last statement in a subprogram or statement 
block and must match the statement that established the subprogram or statement block. 



General Rules 



1. 
2. 

3. 

4. 



When an END statement marking the end of a main program executes, BASIC closes all 
files and releases all program storage. 

BASIC cannot execute an END statement that marks the end of a program unit while an 
error is being handled. The module must execute a RESUME or ON ERROR statement 
before the END statement. 

BASIC signals an error when a program contains an END block statement with no corre- 
sponding and preceding block keyword. 

When BASIC executes an END DEF or END FUNCTION statement, it returns the function 
value to the statement that invoked the function and releases all storage associated with the 
DEF or FUNCTION. 
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TUa PWn nFF ctatpmpnt rpctnrpc; thp prrnr hanrllinp in pffprt whpn the DEF W3S invoked. 



I 1 H_ L_t 1 l^r 



6. Error handlers set up in DEF* statements are global. The END DEF statement does not 
restore the error handling in effect when the DEF* was invoked. 

7. The END SUB and END FUNCTION statements do not affect I/O operations or files. 

8. The END SUB statement releases the storage allocated to local variables and returns con- 
trol to the calling program. 

9. The END SUB statement cannot be executed in an error handier unless the SUBEND is in a 
subprogram called by the error handler. 

Examples 

300 IF ft = 20 

THEN PRINT "Bye" 

GOTO 327B7 
ELSE GOTO 100 
END IF 



32767 END 
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13.0 EXIT 

Function 

The EXIT statement lets you exit from a SUB or FUNCTION subprogram, a multi-line DEF or from 
statement block. 

Format 



EXIT block 



block: I DEF 

FUNCTION 

SUB 

label 



Syntax Rules 



1. The FUNCTION, SUB, and DEF keywords specify the type of subprogram or multi-line 
DEF from which BASIC is to exit. 

2. Label specifies a statement label for an IF, SELECT, FOR, WHILE, or UNTIL statement 
block. 



General Rules 



1 . An EXIT DEF, EXIT FUNCTION, or EXIT SUB statement is equivalent to an unconditional 
branch to an END DEF, END FUNCTION, or END SUB statement. Control then passes to 
the statement that invoked the DEF or to the statement following the statement that called 
the subprogram. 

2. The EXIT label statement is equivalent to an unconditional branch to the first statement 
following the end of the IF, SELECT, FOR, WHILE, or UNTIL statement labelled by the 
label. 

3. An error handler cannot execute an EXIT FUNCTION or EXIT SUB statement unless the 
error handler calls the FUNCTION or SUB subprogram. 

4. An EXIT FUNCTION or EXIT SUB statement cannot be used within a multi-line DEF 
function. 

5. When the EXIT FUNCTION or EXIT SUB statement executes, BASIC releases all storage 
allocated to local variables and returns control to the calling program. 
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examples 

100 L00P-1: FOR IX = 1% TO 10% 

PRINT 1% 
IF IX = 5X 
THEN EXIT LOOP.l 
END IF 
NEXT IX 



5000 SUB SUBA 



BOOO EXIT SUB 



10000 END SUB 



BASIC Reference Manual 165 



EXTERNAL 
14.0 EXTERNAL 

Function 

The EXTERNAL statement declares constants, variables, functions, and subroutines external to your 
program. You can describe parameters for external functions and subroutines. 

Format 



External Constants 

EXTERNAL data-type CONSTANT const-nam,... 
External Variables 

EXTERNAL data-type unsubs-vbl-nam,... 
External Functions 

EXTERNAL data-type FUNCTION { func-nam [ pass-mech ] [ ( [ external-param ],...)]},. 
External Subroutines 

EXTERNAL SUB { sub-nam [ pass-mech ] [ ( [ external-param ],... ) ] },... 



pass-mech: I BY DESC 

BYREF 
BY VALUE 



external-param: [ data-type ] [ DIM ([,]...) ] [ = int-const ] [ pass-mech ] 



Syntax Rules 

1 . For external variables, data-type can be any valid numeric data type. 

2. For external constants, data-type can be: 

• For VAX-11 BASIC: BYTE, WORD, LONG, SINGLE, INTEGER (any size), or REAL (if 
the default size is SINGLE). 

• For BASIC-PLUS-2: WORD, or INTEGER (if the default size is WORD). 

3. For external functions and subroutines, data-type can be any BASIC data-type keyword 
or, in VAX-1 1 BASIC, a data type defined by a RECORD statement. Data-type keywords, 
size, range, and precision are listed in Table 2 in this manual. 
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4. In WAX-) 1 BASIC, the name of an external constant, variable, function, or subroutine can /\ 
consist of from 1 to 31 characters and must conform to the following rules: \y 

• The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), periods (.), and underscores (_). 

• Quoted names are allowed for the EXTERNAL SUB statement only. Quoted names can I 
consist of any combination of printable ASCII characters. | 

• An EXTERNAL SUB or EXTERNAL FUNCTION statement with empty parentheses speci- 
fies that the named subprogram has zero arguments. 

5. An EXTERNAL SUB or EXTERNAL FUNCTION statement with no parentheses specifies that I 
the named subprogram may receive any number of arguments. | 

6. In BASIC-PLUS-2, the name of an external constant, variable, or subroutine can consist of /^\ 
from one to six characters and must conform to the following rules: V_y 

• The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), and periods (.). 

• Quoted names are allowed for the EXTERNAL SUB statement only. Quoted names can 
consist of any combination of alphabetic characters, digits, dollar signs, periods, and 
spaces. 

External Functions and Subroutines 

1 . The data-type that precedes the FUNCTION keyword defines the data type of the function 
result. 

2. Pass-mech specifies how parameters are to be passed to the function or subroutine. 

• A pass-mech clause outside the parentheses applies to all parameters. 

• A pass-mech clause inside the parentheses overrides the previous pass-mech and applies 
only to the specific parameter. 

3. External-param defines the form of the arguments passed to the external function or 
subprogram. 

• Empty parentheses indicate that the function or subroutine is being named, but that 
parameters are not being defined. 

• Data-type specifies the data type of a parameter. If you do not specify a data type, 
parameters are of the default data type and size. When you do specify a data type, all 
following parameters are of that data type until you specify a new data type. 
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• The DIM keyword indicates that the parameter is an array. Commas specify array dimen- 
sions. The number of dimensions is enual tn tfip nnmhpr nf mmm.c r,i,,c ™ Q rw 
example: 

100 EXTERNAL STRING FUNCTION NEW (DOUBLE, STRING DIM<»>, DIMO) 

This example declares a function named NEW that has three parameters. The first is a 
double-precision floating-point value, the second is a two-dimensional string array, and 
the third is a one-dimensional string array. The function returns a string result. 

• You can specify how an argument is to be passed to the function or subprogram with the 
optional pass-mech clause. If you do not specify a passing mechanism for a parameter, 
BASIC passes arguments by the default passing mechanisms listed in Tables 19 and 20.' 

General Rules 

1 . The EXTERNAL statement must precede any program reference to the constant, variable, 
function, or subroutine declared in the statement. 

2. The EXTERNAL statement is not executable. 

3. A name declared in an EXTERNAL CONSTANT statement may be used in any nondeclara- 
tive statement as if it were a constant. 

4. A name declared in an EXTERNAL FUNCTION statement may be used as a function 
invocation in an expression. 

5. A name declared in an EXTERNAL SUB statement may be used in a CALL statement. 

6. The optional pass-mech clauses in the EXTERNAL FUNCTION and EXTERNAL SUB 
statements tell BASIC how to pass arguments to a non-BASIC function or subprogram. 
Table 19 describes VAX-// BASIC parameter passing mechanisms. Table 20 describes 
BASIC-PLUS-2 parameter passing mechanisms. 

• BY REF specifies that BASIC passes the argument's address. This is the default for all 
arguments except strings and entire arrays. 

• BY VALUE specifies that VAX-1 1 BASIC passes the argument's 32-bit value and that 
BASIC-PLUS-2 passes the argument's 1 6-bit value. 

• BY DESC specifies that BASIC passes the address of a VAX-1 1 BASIC descriptor 
or a BASIC-PLUS-2 descriptor. For information about the format of a VAX-1 1 BASIC 
descriptor for strings and arrays, see Appendix C in BASIC on VAX/VMS Systems. 
BASIC-PLUS-2 creates descriptors only for strings and arrays; these descriptors are de- 
scribed in Appendix C in BASIC on RSX-11M IM-PLUS Systems and BASIC on RSTS/E 
Systems. 
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-7 tu« ^^..^^n+r r>-. C m^ t^» ovtorn^l fnnr-tinnc ^nrl qi ihrni itinp<; should match the external 
parameters declared in the EXTERNAL FUNCTION or EXTERNAL SUB statement in num- 
ber, type, ordinality, and passing mechanism as BASIC forces arguments to conform to the 
declared parameters. BASIC signals an error when conformance is impossible (for exam- 
ple, when a STRING argument is passed where an INTEGER parameter was declared) and 
an informational message when a conversion results in a modifiable parameter becoming a 
nonmodifiable parameter. 

Examples 

External Constants 

100 EXTERNAL LONG CONSTANT SYS$FC 

Externa/ Variables 

100 EXTERNAL WORD SYSNUM 

External Functions 

100 EXTERNAL DOUBLE FUNCTION USR$2 (DOUBLE DIM (.) .BYTE BY VALUE) 

External Subroutines 

100 EXTERNAL SUB CALC BY DESC (STRING DIM(.). BYTE BY REF) 
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he n cici n 

Function 

Note 

The FIELD statement is supported only for compatibility with BASIC-PLUS. Because 
data defined in the FIELD statement can be accessed only as string data, you must use 
the CVTxx functions to process numeric data. This means that you must convert string 
data to numeric after you move it from the I/O buffer. Then, after processing, you 
must convert numeric data back to string data before transferring it to the I/O buffer. 
DiGiTAL recommends that you use BASIC'S dynamic mapping feature or multiple 
MAPs instead of the FIELD statement and CVTxx functions. 

The FIELD statement dynamically associates string variables with all or parts of an I/O buffer. FIELD 
statements do not move data. Instead, they permit direct access through string variables to sections of 
a specified I/O buffer. 

Format 



FIELD chnl-exp, int-exp AS str-vbl [ , int-exp AS str-vbl ]... 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be preceded by a pound sign (#). A file must be open on the specified channel or 
BASIC signals an error. 

2. Int-exp specifies the number of characters in the str-vbl that follows the AS keyword. 



General Ruies 



1 . A FIELD statement is executable. You can change a buffer description at any time by 
executing another FIELD statement. For example: 

100 FIELD »1%» 40% AS WHQLE_FIELD$ 

FIELD #1%. 10% AS A$» 101 AS B$ > 10% AS C* > 10% AS D* 

The first FIELD statement associates the first 40 characters of a buffer with the variable 
WHOLE_FlELD$. The second FIELD statement associates the first 10 characters of the 
same buffer with A$, the second 10 characters with B$, and so on. Later program state- 
ments can refer to any of the variables named in the FIELD statements to access specific 
portions of the buffer. 

2. You cannot define virtual array strings as string variables in a FIELD statement. 

3. See the BASIC-PLUS Language Manual for more information on the FIELD statement. 



BASIC Reference Manual 169 



FIELD 



vax> VAX-11 BASIC 




1 . A variable named in a FiELu statement cannot be used in a COMMON or MAP statement, 
as a parameter in a CALL or SUB statement, or in a MOVE statement. 

2. Using the FIELD statement on a VIRTUAL file that contains a virtual array causes BASIC to 
signal "Illegal or illogical access" (ERR =136). 

3. If you name an array in a FIELD statement, you cannot use MAT statements of the format: 
MAT arr-nam1 = arr-nam2 

or 

MATarr-nam1 = NUL$ 

where arr-naml is named in the FIELD statement. An attempt to do so causes BASIC to 
signal a compile-time error. 



Examples 

100 FIELD «8Z» 21 AS U$ , 21 AS CL$ , Q% AS X$ , HI AS Y* 
210 LSET U$ = CVTX$(U%> 

LSET CL* = CVTXf(CLZ) 

LSET X$ = CyTF$(X) 

LSET Y$ = CUTF*(Y) 
300 U% = CMT*Z(U$) 

CL% = CYT*%(CL$) 

X = CyT$F(X$) 

Y = CVT*F(Y$) 



Note 

DIGITAL does not recommend the FIELD statement for new program development. 
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16.0 FIND 

Function 

The FIND statement locates a specified record in a disk file and makes it the Current Record for a 
GET, UPDATE, or DELETE operation. FIND statements are valid on RMS sequential, relative, in- 
dexed, and block I/O files. You should not use FIND statements on terminal-format files, virtual array 
files, or files opened with ORGANIZATION UNDEFINED. 

Format 

VAX-11 BASIC 



FIND chnl-exp [ , position-clause ] [ , lock-clause 



RFA rfa-exp 
position-clause: \ RECORD num-exp 
KEY# key-clause 



lock-clause: 



allow-clause: 



ALLOW allow-clause 
REGARDLESS 



NONE 
READ 
MODIFY 



key-clause: 



rel-op: 



int-exp1 rel-op 



EQ 
GE 
GT 



str-exp 

int-exp2 

decimal-exp 



(continued on next page) 
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BP2) BASIC-PLUS-2 



FIND chni-exp [ , position-clause ] 



RFA rfa-exp 
position-clause: { RECORD num-exp 
KEY# key-clause 



key-clause: 


int-exp1 rel-op 




EQ 




rel-op: 


GE 
GT 





str-exp 
int-exp2 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Position-clause specifies the position of a record in a file. BASIC signals an error if you 
specify a position-clause and chnl-exp is not associated with a disk file. 

• If you do not specify a position-clause, FIND locates records sequentially. Sequential 
record access is valid on RMS sequential, relative, indexed, and block I/O files. 

• The RFA position-clause allows you to randomly locate records by specifying the Record 
File Address (RFA) of a record. That is, you specify the disk address of a record, and RMS 
locates the record at that address. All RMS file organizations may be accessed by RFA. 

• The RECORD position-clause allows you to randomly locate records in relative and 
block I/O files by specifying the record number. 

• The KEY position-clause allows you to randomly locate records in indexed files by speci- 
fying a key of reference, a relational test, and a key value. 

3. Rfa-exp in the RFA position-clause is a variable of the RFA data type that specifies the 
record's Record File Address. Note that an RFA expression can only be a variable of the 
RFA data type or the GETRFA function. Use the GETRFA function to find the RFA of a 
record. 

4. Int-exp in the RECORD position-clause specifies the number of the record you want to 
locate. It must be between one and the file's maximum record number. 
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5. In the key-clause: 

• Int-exp1 is the target key of reference. It must be a WORD or LONG integer between 
zero and the highest-numbered key for the file, inclusive. BASIC converts BYTE integers 
to WORD. The primary key is key number zero, the first alternate key is key number 
one, the second alternate key is key number two, and so on. Int-exp1 must be preceded 
by a pound sign (#) or BASIC signals an error. 

• Str-exp and int-exp2 specify a string or integer value to be compared with the key value 
of a record. 

• Rel-op specifies how str-exp or int-exp2 is to be compared to int-expl. EQ means "equal 
to," GE means "greater than or equai to," and GT means "greater than." 

6. When you specify a RECORD clause, chnl-exp must be a channel associated with an open 
relative or block I/O file. 

7. When you specify a KEY clause, chnl-exp must be a channel associated with an open 
indexed file. 

VAX- 7 1 BASIC <¥Ax) 

1 . Str-exp in the KEY clause cannot be a null string. 

2. Decimal-exp in the KEY clause specifies a packed decimal value to be compared with the 
key value of a record. 

3. Lock-clause allows you to control how a record is locked to other access streams. The file 
associated with chnl-exp must have been opened with the UNLOCK EXPLICIT clause or 
BASIC signals the error "illegal record locking clause". 

4. If you specify a lock-clause, it must follow the position-clause. If the lock-clause precedes 
the position-clause, BASIC signals an error. 

General Rules 

1. The file associated with chnl-exp must be opened with ACCESS MODIFY, READ, or 
SCRATCH before your program can execute a FIND. 

2. FIND does not transfer any data. 

3. A successful sequential FIND updates both the Current Record and Next Record Pointers. 

• For sequential files, a successful FIND locates the next sequential record (the record 
pointed to by the Next Record Pointer) in the file, changes the Current Record Pointer to 
the record just found, and sets the Next Record Pointer to the next sequential record. If 
the Current Record Pointer points to the last record in a file, a sequential find causes 
BASIC to signal "End of file on device" (ERR= 11). 

• For relative files, a successful FIND locates the record with the next higher record num- 
ber (or cell number), makes it the Current Record, and changes the Next Record to the 
Current Record plus one. 
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• For indexed files, a successful FIND locates the next logical record in the current key of 
reference, makes this the Current Record, and changes the Next Record to the Current 
Record plus one. 

• For block I/O files, a successful FIND locates the next disk block (for files with 
RECORDSIZE 512) or the next record (for files with RECORDSIZE greater than 512), 
makes it the Current Record, and changes the Next Record to the Current Record plus 
one. 

4. A successful random FIND by KEY locates the first record whose key satisfies the 
key-clause comparison: 

• With an exact key match (EQ), a successful FIND locates the first record in the file that 
equals the key value given in int-exp or specified by str-exp. The characters specified by 
str-exp are matched approximately rather than exactly. That is, if you specify "ABC" and 
the key length is six characters, BASIC matches the first record that begins with ABC. If 
you specify "ABC ", BASIC matches only a record with the key "ABC ". If no 
match is possible, BASIC signals the error "Record not found" (ERR = 155). 

• With the greater than key match (GT), a successful FIND locates the first record with a 
value greater than int-exp or str-exp. If no such record exists, BASIC signals the error 
"End of file on device" (ERR = 11). 

• If you specify a greater than or equal to key match (GE), a successful FIND locates the 
first record that equals the key value in int-exp or str-exp. If no exact match is possible, 
BASIC locates the first record with a key value higher than int-exp or str-exp. 

5. A successful random access FIND by RFA or by RECORD changes the Current Record 
Pointer to the record specified by rfa-exp or int-exp, but leaves the Next Record Pointer 
unchanged. 

6. A successful random access FIND by KEY changes the Current Record Pointer to the first 
record whose key satisfies the key-clause comparison and the Next Record Pointer to the 
record with the next higher value in the current key. 

7. When a random access FIND by RFA, RECORD, or KEY is not successful, BASIC signals 
"Record not found" (ERR = 155). The values of the Current Record Pointer and Next 
Record Pointer are undefined. 

8. If the RMS index lists are in memory, a FIND on an indexed file does not initiate any disk 
operations. 
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The type of lock you impose on a record remains in effect until you explicitly unlock it with 
a FREE or UNLOCK statement or until you close the file. 

• ALLOW NONE specifies no access to the record. This means that other access streams 
cannot retrieve the record unless they bypass lock checking with GET REGARDLESS. 

• ALLOW READ specifies read access to the record. This means that other access streams 
. can retrieve the record but cannot PUT or UPDATE the record. 

• ALLOW MODIFY specifies both read and write access to the record. This means that 
other access streams can GET, PUT, DELETE, or UPDATE the record. 
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2. When you do not specify an ALLOW clause, locking is imposed as follows: 

• If the file associated with chnl-exp was opened with UNLOCK EXPLICIT, BASIC imposes 
the ALLOW NONE lock on the retrieved record and the next GET or FIND does not 
unlock the previously locked record. 

• If the file associated with chnl-exp was not opened with UNLOCK EXPLICIT, BASIC locks 
the retrieved record and unlocks the previously locked record. 

BASIC-PLUS-2 (BP2 

1 . When you access a shared file, a successful FIND locks the record or bucket and unlocks 
the previously iocked record or bucket. 

Examples 

Sequential Access 

100 MAP (XYZ) STRING LAST_NAME = 10. FIRST-NAME - G 
150 OPEN 'EMP.DAT' AS FILE *i . & 

ORGANIZATION SEQUENTIAL. MAP XYZ 
200 FIND #1 

Random Access 

100 DECLARE RFA Address(99> 

200 MAP (XYZ) STRING LAST-NAME = 10 t FIRST_NAME = B 

300 OPEN 'EMP.DAT' AS FILE #1. 8. 

ORGANIZATION SEQUENTIAL. MAP XYZ 
400 FIND *1 

Address(O) = GETRFA(l) 

! 

! 

! 

500 FIND *1> RFA Address(S) 
i 

! 
600 OPEN 'NEWEMP.DAT' AS FILE #2. & 

ORGANIZATION RELATIVE. MAP XYZ 
700 FIND *2> RECORD A/f. 

Address(AX) = GETRFA<2> 

! 

! 

! 

FIND *2 . RFA Add ress ( A% ) 

! 

900 OPEN 'OLDEMP.DAT' AS FILE *3 . & 

ORGANIZATION INDEXED. MAP XYZ, & 
PRIMARY KEY LAST-NAME 
FIND *3. KEY #0 EQ "JONES" 
Address(5> = GETRFAO) 



FIND «3. RFA Address<7> 
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VAX-11 BASIC 

100 MAP <XYZ) STRING LAST-NAME = 10; FIRST-NAME = 6 
200 OPEN 'EMP.DAT' AS FILE *lT ■ ».w,_.,rn.„_ u ^ 

ORGANIZATION INDEXED, g, 

MAP XYZ, PRIMARY KEY LAST-NAME, 8, 

UNLOCK EXPLICIT 
400 FIND «3, KEY «0 EQ "JONES", ALLOW READ 
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MM l-NCIMU 

Function 

The FNEND statement is a synonym for END DEF. See the END statement for syntax rules. 

Format 



FNEND 
END DEF 
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FNEXIT 
18.0 FNEXIT 

Function 

The FNEXIT statement is a synonym for the EXIT DEF statement. See the EXIT statement for syntax 
rules. 

Format 



FNEXIT 
EXIT DEF 
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19.0 FOR 

Function 

The FOR statement repeatedly executes a block of statements, while incrementing a specified control 
variable for each execution of the statement block. FOR loops can be conditional or unconditional, 
and can modify other statements. 

Format 



Unconditional 


FOR num-unsubs-vbl = num-exp1 TO num-exp2 [ STEP num-exp3 ] 


[ statement ]... 


NEXT num-unsubs-vbl 


Conditional 




UNTIL 




FOR num-unsubs-vbl = num-exp1 [ STEP num-exp3 ] 


WHILE 


cond-exp 


[ statement ]... 


NEXT num-unsubs-vbl 


Unconditional Statement Modifier 


statement FOR num-unsubs-vbl = num-exp1 TO num-exp2 [ STEP num-exp3 ] 


Conditional Statement Modifier 




UNTIL 




statement FOR num-unsubs-vbl = num-exp1 [ step num-exp3 ] 


WHILE 


cond-exp 



Syntax Rules 

1 . Num-unsubs-vbl is the loop variable. It is incremented each time the loop executes. 

2. In unconditional FOR loops, num-exp1 is the initial value of the loop variable, while 
num-exp2 is the maximum value. 

3. In conditional FOR loops, num-expl is the initial value of the loop variable, while the 
cond-exp in the WHILE or UNTIL clause is the condition that controls loop iteration. 

4. Num-exp3 in the STEP clause is the value by which the loop variable is incremented after 
each execution of the loop. 

5. In VAX-/ 7 BASIC, you can nest FOR loops to a maximum of 12 levels, depending on the 
complexity of the loops. 
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6. In BASIC-PLUS-2, you nest FOR loops to a maximum of 8 levels, depending on the 

rnmnlpyitv nf th<=» Innnc 

7. An inner loop must be entirely within an outer loop; the loops cannot overlap. 

8. You cannot use the same loop variable in nested FOR loops. That is, if the outer loop uses 
"FOR I = 1 TO 10", you cannot use the variable ! as a loop variable in an inner loop. 

9. The default for num-exp3 is one if there is no STEP clause. 

10. You can transfer control into a FOR loop only be returning from a function invocation, a 
subprogram call, or an error handler that was invoked in the loop. 

11. Each FOR statement must have a corresponding NEXT statement or BASIC signals and 
error. 

General Rules 

1. The starting, incrementing, and ending values of the loop do not change during loop 
execution. 

2. The loop variable can be modified inside the FOR loop. 

3. BASIC converts num-expl , num-exp2, and num-exp3 to the data type of num-unsubs-vbl 
(the loop variable) before storing them. 

4. When an unconditional FOR loop ends, the loop variable contains the value last used in 
the loop, not the value that caused loop termination. 

5. During each iteration of a conditional loop, BASIC tests the value of cond-exp before it 
executes the loop. 

• If you specify a WHILE clause and cond-exp is false (value zero), BASIC exits from the 
loop. If the cond-exp is true (value nonzero), the loop executes again. 

• If you specify an UNTIL clause and cond-exp is true (value nonzero), BASIC exits from 
the loop. If the exp is false (value zero), the loop executes again. 

6. When FOR is used as a statement modifier, BASIC executes the statement until 
num-unsubs-vbl equals or exceeds num-exp2 or until the WHILE or UNLESS condition is 
satisfied. 

Examples 

Unconditional 

350 FOR I = 3 TO 99 STEP 3 



400 NEXT I 

Unconditional 

100 FOR Z = STEP 2 UNTIL X 



200 NEXT Z 
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Unconditional Statement Modifier 

100 A = A + ,0005 FOR I = 1 TO 10 

Conditional Statement Modifier 

100 FIND #2 FOR I = 1 UNTIL ERR=155 
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| 20.0 FREE (VAX-11 BASIC) 

Function 

The FREE statement unlocks all records and buckets associated with a specified channel. 
Format 



FREE chnl-exp 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

General Rules 

1 . The file specified by chnl-exp must be open. 

2. You cannot use the FREE statement with files not on disk. 

3. If there are no locked records or buckets on the specified channel, the FREE statement has 
no effect and BASIC does not signal an error. 

4. The FREE statement does not change record buffers or pointers. 

5. Your program must execute a GET or FIND statement after a FREE statement executes 
before a PUT statement can execute. 

Examples 

450 FREE «BX 
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21.0 FUNUMUN 

Function 

The FUNCTION statement marks the beginning of a FUNCTION subprogram and defines the subpro- 
gram's parameters. 

Format 

VAX-11 BASIC 




VAX) 



FUNCTION data-type func-nam [ pass-mech ] [ ( [ formal-param ],... ) ] 

[ statement ]... 

j END FUNCTION ' 
FUNCTIONEND 



pass-mech: 



formal-param: 



BYREF 
BY DESC 



data-type 



unsubs-vbl-nam 
array-nam ( f int-const 



) 



. [ = int-const ] [ pass-mech 



BASIC-PLUS-2 



(BP2l 



FUNCTION data-type func-nam [ ( [ formal-param ],... ) ] 

[ statement ]... 

END FUNCTION 
FUNCTIONEND 



formal-param: I unsubs-vbl-nam 

[ data-type ] / array-nam ( int-const 
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Syntax Rules 

1 . Func-nam names the FUNCTION subprogram. The last character of the name cannot be a 
dollar sign ($). 

2. Data-type can be any BASIC data-type keyword or, in VAX-1 1 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manuai. 

3. The data-type that precedes the func-nam specifies the data type of the value returned bv 
the FUNCTION subprogram. 

4. Formal-param specifies the number and type of parameters for the arguments the 
FUNCTION subprogram expects to receive when invoked. 

• Empty parentheses indicate that the FUNCTION subprogram has zero parameters. 

• Data-type specifies the data type of a parameter. If you do not specify a data type, 
parameters are of the default data type and size. When you do specify a data type, all 
following parameters are of that data type until you specify a new data type. 

• If you specify a data-type, unsubs-vbl-nam and array-nam cannot end in a percent sign 
(%) or dollar sign ($). 

• Parameters defined in formal-param must agree in number and type with the arguments 
specified in the function invocation. 

5. The FUNCTION statement must be the first statement in the FUNCTION subprogram. 

6. Compiler directives and comment fields (!), because they are not BASIC statements, may 
precede the FUNCTION statement. However, they cannot precede the subprogram's first 
numbered line. Note that REM is a BASIC statement; therefore, it cannot precede the 
FUNCTION statement. 

7. Every FUNCTION statement must have a corresponding END FUNCTION statement or 
FUNCTIONEND statement. 

8. Any BASIC statement except END, SUB, SUBEND, END SUB, or SUBEXIT can appear in a 
FUNCTION subprogram. 

VAX-1 1 BASIC 

1 . Func-nam can consist of from 1 to 31 characters The first character must be an alphabetic 
character (A through Z). The remaining characters, if present, can be any combination of 
letters, digits (0 through 9), dollar signs ($), periods (.), or underscores (_). 

2. If the data type is STRING, the =int-const clause allows you to specify the length of the 
string. The default string length is 16. 

3. VAX-1 1 BASIC allows you to specify from 1 to 32 formal-params. 
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program receives arguments when invoked. A pass-mech should be specified only when 
the FUNCTION subprogram is being called by a non-BASIC program. 

5. A pass-mech clause outside the parentheses applies by default to all FUNCTION parame- 
ters. A pass-mech clause in the formal-param list overrides the specified default and applies 
only to the immediately preceding parameter. 

BASIC-PLUS-2 (era) 

1 . Func-nam can consist of from one to six characters. The first character must be an alpha- | 
betic character (A through Z). The remaining characters, if present, can be any combina- 
tion of letters, digits (0 through 9), dollar signs ($), and periods (.). 

2. BASIC-PLUS-2 allows you to specify from one to eight formal-params. 

General Rules 

1. FUNCTION subprograms must be declared with the EXTERNAL statement before your 
program can invoke them. 

2. FUNCTION subprograms receive parameters BY REF or BY DESC. 
BY REF specifies that the FUNCTION subprogram receives the argument's address. 

BY DESC specifies that the FUNCTION subprogram receives the address of a VAX-11 
BASIC descriptor or a BASIC-PLUS-2 descriptor. For information about the format of a 
VAX-1 1 BASIC descriptor for strings and arrays, see Appendix C in BASIC on VAX/VMS 
Systems; for information on other types of descriptors, refer to the VAX Architecture 
Handbook. BASIC-PLUS-2 creates descriptors only for strings and arrays; these descrip- 
tors are described in Appendix C in BASIC on RSX-1 1M/M-PLUS Systems and BASIC on 
RSTS/E Systems. 

3. All variables and data, except virtual arrays, COMMON areas, and MAP areas in a 
FUNCTION subprogram, are local to the subprogram. 

4. BASIC initializes local numeric variables to zero and local string variables to the null string 
each time the FUNCTION subprogram is invoked. 

5. ON ERROR GO BACK is the default error handler for a FUNCTION subprogram. 

BASIC-PLUS-2 (spa) 

1. BASIC-PLUS-2 receives numeric unsubs-vbls BY REF and string unsubs-vbls and entire 
arrays BY DESC. 



VAX-1 1 BASIC <vax 



1 . By default, VAX-1 1 BASIC FUNCTION subprograms receive numeric unsubs-vbls BY REF, 
and all other parameters BY DESC. You can override these defaults with a BY clause: 

• Any parameter can be received BY DESC. 

• To receive a string parameter BY REF, you must specify the string length. 

• To receive an entire array BY REF, you must specify the array bounds. 
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Examples 

VAX-? 1 BASIC only 

100 FUNCTION GFLOAT SIGMA BY DESC & 
(GFLOAT A(20,Z0> » & 
Bt HFLOAT C BY REF) 



250 END FUNCTION 

BASIC-PLUS-2 only 

100 FUNCTION DOUBLE CALC (SINGLE A, B, DOUBLE C<10»50) 
250 END FUNCTION 
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22.0 FUNCTIONEND 



Function 



The FUNCTIONEND statement is a synonym for the END FUNCTION statement. See the END 
statement for syntax rules. 

Format 



FUNCTIONEND 
END FUNCTION ) 
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23.0 FUNCTIONEXIT 



Function 



The FUNCTIONEXIT statement is a synonym for the EXIT FUNCTION statement. See the EXIT state- 
ment for syntax rules. 

Format 



FUNCTIONEXIT 
EXIT FUNCTION 
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24.0 GET 

Function 

The GET statement moves a record from a file to a record buffer and makes the data available for 
processing. GET statements are valid on RMS sequential, relative, indexed, and block I/O files, and 
on RSTS/E non-RMS block I/O files. You should not use GET statements on terminal-format files, 
virtual array files, or files opened with ORGANIZATION UNDEFINED. 

Format 

V.AX-11 BASIC 



GET chnl-exp [ , position-clause ] [ , lock-clause ] 




RFA rfa-exp j 


position-clause: 


RECORD num-exp } 
KEY# key-clause } 


lock-clause: 


ALLOW allow-clause 
REGARDLESS 






NONE j 


allow-clause: 


READ J 




MODIFY ) 




| str-exp 




key-clause: 


int-exp1 rel-op { int-exp2 

( decimal-exp 






EQ ) 


rel-op: 


GE 




GT J 



\z 



(continued on next page) 
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BP2) BASIC-PLUS-2 



GET chnl-exp [ , position-clause ] 



RFA rfa-exp 
position-clause: { RECORD num-exp 
KEY# key-clause 



key-clause: int-exp1 rel-op 



EQ 

rel-op: { GE 

GT 



str-exp 
int-exp2 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Position-clause specifies the position of a record in a file. BASIC signals an error if you 
specify a position-clause and chnl-exp is not associated with a disk file. 

• If you do not specify a position-clause, GET retrieves records sequentially. Sequential 
record access is valid on RMS sequential, relative, indexed, and block I/O files. 

• The RFA position-clause allows you to randomly retrieve records by specifying the Rec- 
ord File Address (RFA) of a record. That is, you specify the disk address of a record, and 
RMS retrieves the record at that address. All RMS file organizations may be accessed by 
RFA. 

• The RECORD position-clause allows you to randomly retrieve records in relative and 
block I/O files by specifying the record number. 

• The KEY position-clause allows you to randomly retrieve records in indexed files by 
specifying a key of reference, a relational test, and a key value. 

3. Rfa-exp in the RFA position-clause is an expression of the RFA data type that specifies the 
record's Record File Address. Note that an RFA expression can be only a variable of the 
RFA data type or the GETRFA function. Use the GETRFA function to find the RFA of a 
record. 

4. Int-exp in the RECORD position-clause specifies the number of the record you want to 
retrieve. It must be between one and the file's maximum record number. 
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5. In the key-clause: 

• Int-exp1 is the target key of reference. It must be a WORD or LONG integer between 
zero and the highest-numbered key for the file, inclusive. BASIC converts BYTE integers 
to WORD. The primary key is key number zero, the first alternate key is key number one, 
the second alternate key is key number two, and so on. Int-expl must be preceded by a 
pound sign (#) or BASIC signals an error. 

• Str-exp and int-exp2 specify a string or integer value to be compared with the key value of 
a record. Str-exp can contain fewer characters than the key of the record you want to 
retrieve. 

• Rel-op specifies how sfr-exp or int-exp2 is to be compared to int-expl. EQ means "equal 
to," GE means "greater than or equal to," and GT means "greater than." 

6. When you specify a RECORD clause, chnl-exp must be a channel associated with an open 
relative or block I/O file. 

7. When you specify a KEY clause, chnl-exp must be a channel associated with an open 
indexed file. 

VAX-11 BASIC <vax) 

1 . Str-exp in the KEY clause cannot be a null string. 

2. Decimal-exp in the KEY clause specifies a packed decimal value to be compared with the 
key value of a record. 

3. Lock-clause allows you to control how a record is locked to other access streams or to 
override lock checking when accessing shared files that may contain locked records. 

4. If you specify a lock-clause, it must follow the position-clause. If the lock-clause precedes 
the position-clause, BASIC signals an error. 

5. If you specify an allow-clause, the file associated with chnl-exp must have been opened 
with the UNLOCK EXPLICIT clause or BASIC signals the error "illegal record locking 
clause". 

General Rules 

1. The file specified by chnl-exp must be open with ACCESS READ or MODIFY before your 
program can execute a GET. The default ACCESS clause is MODIFY. 

2. If the last I/O operation was a successful FIND, a sequential GET retrieves the Current 
Record located by the FIND and sets the Next Record Pointer to the Current Record plus 
one. 

3. If the last I/O operation was not a FIND, a sequential GET retrieves the Next Record and 
sets the Next Record Pointer to the Current Record plus one. 

• For sequential files, a sequential GET retrieves the next record in the file. 

• For relative and block I/O files, a sequential GET retrieves the record with the next 
higher cell number. 

• For indexed files, a sequential GET retrieves the record with the next higher value in the 
current key of reference. 
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4. A successful random GET by RFA or by RECORD retrieves the record specified by rfa-exp 
or int-exp. 

5. A successful random GET by KEY retrieves the first record whose key satisfies the 
key-clause comparison: 

• With an exact key match (EQ), a successful GET retrieves the first record in the file that 
equals the key value given in int-exp or specified by str-exp. The characters specified by 
str-exp are matched approximately rather than exactly. That is, if you specify "ABC" and 
the key length is six characters, BASIC matches the first record that begins with ABC. If 
you specify "ABC ", BASIC matches only a record with the key "ABC ". If no 
match is possible, BASIC signals the error "Record not found" (ERR = 155). 

• With the greater than key match (GT), a successful GET retrieves the first record with a 
value greater than int-exp or str-exp. If no such record exists, BASIC signals the error "End 
of file on device" (ERR = 11). 

• If you specify a greater than or equal to key match (GE), a successful GET retrieves the 
first record that equals the key value in int-exp or str-exp. If no exact match is possible, 
BASIC retrieves the first record with a key value higher than int-exp or str-exp. 

6. A successful random GET by RFA, RECORD, or KEY sets the value of the Current Record 
Pointer to the record just read. The Next Record Pointer is set to the Current Record plus 
one. 

7. An unsuccessful GET leaves the record pointers and the I/O buffer in an undefined state. 

8. If the retrieved record is smaller than the receiving buffer, BASIC fills the remaining buffer 
space with nulls. 

9. If the retrieved record is larger than the receiving buffer, BASIC truncates the record and 
signals an error. 

10. A successful GET sets the value of the RECOUNT variable to the number of bytes trans- 
ferred from the file to the record buffer. 

11. Because a GET statement on a block I/O file always transfers an integral number of 
512-byte disk blocks, your program must perform record blocking and deblocking. See 
Chapter 9 in the BASIC User's Guide for more information. 



vax> VAX-/ / BASIC 



1 . The type of lock you impose on a record remains in effect until you explicitly unlock it with 
a FREE or UNLOCK statement or until you close the file. 

• ALLOW NONE specifies no access to the record. This means that other access streams 
cannot retrieve the record unless they bypass lock checking with GET REGARDLESS. 

• ALLOW READ specifies read access to the record. This means that other access streams 
can retrieve the record, but cannot PUT or UPDATE the record. 

• ALLOW MODIFY specifies both read and write access to the record. This means that 
other access streams can GET, PUT, DELETE, or UPDATE the record. 
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2. When you do not specify an ALLOW clause, locking is imposed as follows: 

• If the file associated with chnl-exp was opened with UNLOCK EXPLICIT, BASIC imposes 
the ALLOW NONE lock on the retrieved record and the next GET or FIND does not 
unlock the previously locked record. 

• If the file associated with chnl-exp was not opened with UNLOCK EXPLICIT, BASIC locks 
the retrieved record and unlocks the previously locked record. 

3. REGARDLESS specifies that the GET statement can override lock checking and read a 
record locked by another program. 

4. REGARDLESS does not impose a lock on the retrieved record. 

BASIC-PLUS-2 (BP2S 

1 . When you access a shared file, a successful GET locks the record or bucket and unlocks 
the previously locked record or bucket. 

Examples 

Sequential Access 

100 MAP <XYZ) STRING LAST-NAME = 10, FIRST_NAME = B 
150 OPEN 'EMP.DAT' AS FILE #1, & 

ORGANIZATION SEQUENTIAL, MAP XYZ 
200 GET #4 

Random Access 

100 MAP (XYZ) STRING LAST-NAME = 10, FIRST-NAME = 6 

200 DECLARE RFA AddressOS) 

300 OPEN 'EMP.DAT' A3 FILE *i, & 

ORGANIZATION SEQUENTIAL, MAP XYZ 
400 GET *1 

Address(O) = GETRFA(l) 

! 

500 GET #1, RFA Address(5) 
! 

600 OPEN 'NEWEMP.DAT' AS FILE *2 , & 

ORGANIZATION RELATIVE, MAP XYZ 
700 GET *2» RECORD AX 

Address(AZ) = GETRFA<2) 



FIND »2, RFA Address(A%> 



(continued on next page) 
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900 OPEN 'OLDEMP.DAT' AS FILE *3 , L 

ORGANIZATION INDEXED* MAP XYZ » & 

PRIMARY KEY LAST.NAME 

GET *3, KEY *0 EO "JONES" 

Address(5> = GETRFAO) 



GET *3< RFA Address<7> 
VAX-1 1 BASIC 



100 MAP (XYZ) STRING LAST_NAME = 10. FIRST-NAME = B 
300 OPEN 'EMP.DAT' AS FILE #1 , & 

ORGANIZATION INDEXED , & 

MAP XYZ, PRIMARY KEY LAST-NAME, & 

UNLOCK EXPLICIT 
400 GET *1 , KEY #0 EO "JONES", ALLOW READ 
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Function 



The GOSUB statement transfers control to a specified line number or label and stores the location of 
the GOSUB statement for eventual return from the subroutine. 

Format 



I an ci in I 
GOSUB 1 target 



Syntax Rules 

1. Target must refer to an existing line number or label in the same program unit as the 
GOSUB statement or BASIC signals an error. 

2. Target cannot be inside a FOR/NEXT, WHILE, or UNTIL loop or a multi-line function 
definition unless the GOSUB statement is also within that loop or function definition. 

General Rules 

None. 

Examples 

200 GOSUB 1100 



1100 



Subroutine 1 



2100 RETURN 
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26.0 GOTO 

Function 

The GOTO statement transfers control to a specified line number or label. 

Format 




Syntax Rules 

1 . Target must refer to an existing line number or label in the same program unit as the GOTO 
statement or BASIC signals an error. 

2. Target cannot be inside a FOR/NEXT, WHILE, or UNTIL loop or a multi-line function 
definition unless the GOTO statement is also inside that loop or function definition. 

General Rules 

None. 

Examples 

20 GOTO 200 
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Function 



The IF statement evaluates a conditional expression and transfers program control depending on the 
resulting value. 

Format 



Conditional 



IF cond-exp 



THEN 



statement., 
lin-num 



GOTO target 



ELSE 



lin-num 
statement.. 



[ END IF ] 



Statement Modifier 

statement IF cond-exp 



Syntax Rules 

Conditional 

1 . Cond-exp can be any valid conditional expression. 

2. Any executable statement is valid in the THEN or ELSE clause, including another IF state- 
ment. You can include any number of statements in either clause. 

3. All statements between the keyword THEN and the next ELSE, line number, or END IF are 
part of the THEN clause. All statements between the ELSE keyword and the next line 
number or END IF are part of the ELSE clause. 

4. You can omit the THEN keyword when the target of a GOTO statement in the THEN is a 
lin-num. The THEN keyword is required when the target of a GOTO statement is a label. 

5. BASIC assumes a GOTO statement when the ELSE keyword is followed by a lin-num. 
When the target of a GOTO statement is a label, the GOTO keyword is required. 

6. If a THEN or ELSE clause contains a FOR, SELECT, UNTIL, or WHILE statement, then a 
corresponding NEXT or END statement must appear in the same THEN or ELSE clause. 

7. IF statements can be nested to 12 levels. 

8. The END IF statement terminates the most recent unterminated IF statement. 

9. A new line number terminates all unterminated IF statements. 
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Statement Modifier 

1 . IF can modify any executable statement except a block statement such as FOR, WHILE, 
UNTIL, or SELECT. 

2. Cond-exp can be any valid conditional expression. 

General Rules 

Conditional 

1 . BASIC evaluates cond-exp for truth or falsity. If true (nonzero), BASIC executes the THEN 
clause. If false (zero), BASIC skips the THEN clause and executes the ELSE clause, if 
present. 

2. The NEXT keyword cannot be in a THEN or ELSE clause unless the IF statement associated 
with the NEXT keyword is also part of the THEN or ELSE clause. 

3. Execution continues at the statement following the END IF or ELSE clause. If the statement 
does not contain an ELSE clause, execution continues at the next statement after the THEN 
clause. 

Statement Modifier 

1 . BASIC executes statement only if the cond-exp is true (nonzero). 

Examples 

Conditional 

19000 IF ERR = 11 
THEN 

IF ERL = 1000 

THEN GOTO ERROR-ROUTINE 

ELSE 

IF ERL = 2000 
THEN 32700 
ELSE 

IF ERL = 3000 
THEN GOTO ERROR.RDUTINE 
END IF 
END IF 
END IF 
ELSE PRINT ERT*(ERR) 
END IF 

Statement Modifier 

100 PRINT 'END OF PROCESSING' IF ERR = 11 
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28.0 INPUT 

Function 

The INPUT statement assigns values from your terminal or from a terminal-format file to program 
variables. 

Format 



INPUT [ chnl-exp, ] [ prompt ] vbl [ sep [ prompt ] vbl ].. 



sep: 



prompt: str-const sep 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Vbl cannot be a DEF function name unless the INPUT statement is inside the multi-line DEF 
that defines the function. 



General Rules 

1 



The default chnl-exp is zero (the controlling terminal). If a chnl-exp is specified, a file must 
be open on that channel with ACCESS READ or MODIFY before the INPUT statement can 
execute. 

2. You can include more than one prompt in an INPUT statement. The first prompt is issued 
for the first vbl, the second prompt for the second vbl, and so on. The sep that follows the 
vbl associated with the prompt has no formatting effect. BASIC always advances to a new 
line when you terminate input with a carriage return. 

3. Sep in the prompt clause determines where the question mark is displayed and where the 
cursor is positioned for input. 

• A comma tells BASIC to skip to the next print zone and display the question mark. For 
example: 

100 INPUT 'NAME' >Y0UR_NAME$ 

Run 

NAME ? 

• A semicolon tells BASIC to display the question mark next to str-const. For example: 

100 INPUT 'ADDRESS' 5ADDR* 

Run 

ADDRESS? 
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4. BASIC signals an error if the INPUT statement has no argument. 

5. If input comes from a terminal, BASIC displays the contents of str-const, if present, and a 
question mark (?). If you have not specified a str-const, BASIC displays only the question 
mark. The program then waits for data. 

6. If the open channel does not correspond to a terminal, BASIC displays only the question 
mark. 

7. When BASIC receives a line terminator or a complete record, it checks each data element 
for correct data type and range limits, then assigns the values to the corresponding 
variables. 

8. If you specify a string variable to receive the input text, and the user enters an unquoted 
string in response to the prompt, BASIC ignores the string's leading and trailing spaces and 
tabs. An unquoted string cannot contain any commas. 

9. When you enter several data elements in response to the INPUT prompt, you must separate 
them with commas. 

10. If there is not enough data in the current record or line to satisfy the variable list, BASIC 
takes one of the following actions: 

• If the input device is a terminal, BASIC repeats the question mark, but not the str-const, 
on a new line until sufficient data is entered. 

• If the input device is not a terminal, BASIC signals "Not enough data in record" 
(ERR = 59). 

11. If there are more data items than variables in the INPUT response, BASIC ignores the 
excess. 

12. If there is an error in converting or assigning data (for example, assigning string data to a 
numeric variable), BASIC takes one of the following actions: 

• If the input device is a terminal, BASIC signals a warning, reexecutes the INPUT state- 
ment, and displays str-const and the question mark. 

• If the input device is not a terminal, BASIC signals "Illegal number" (ERR = 52) or "Data 
format error" (ERR = 50). 

13. When a RESUME statement transfers control to an INPUT statement, the INPUT statement 
retrieves a new record regardless of any data left in the previous record. 

14. After a successful INPUT statement, the RECOUNT variable contains the number of char- 
acters transferred from the file or terminal to the record buffer. 
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15. If you terminate input text with CTRL/Z, BASIC assigns the value to the variable and signals 
"End of file on device" (ERR = 1 1 ) when the next terminal input statement executes. If there 
is no next INPUT, INPUT LINE, or LINPUT statement in the program, the CTRL/Z is passed 
to BASIC as a signal to exit the BASIC environment. BASIC signals "Unsaved changes have 
been made, CTRL/Z or EXIT to exit" if you have made changes to your program. If you 
have not made changes, BASIC exits from the BASIC environment and does not signal an 
error. 

Examples 

*"* ~ ~ * hi w i > ii L a n w J. II i lulu 5 7!-1A>r D Ai t Lr A, 

100 INPUT *3X, REC0RD_STRING$ 

150 INPUT #1%. "PURCHASE NUMBER" 5 PO-NUMX ! "COST"; COST. "ID NUMBER" !ID% 
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29.0 INPUT LINE 



Function 



The INPUT LINE statement assigns a string value, including the line terminator, from a terminal or 
terminal-format file to a string variable. 

Format 



INPUT LINE [ chnl-exp, ] [ prompt ] str-vbl [ sep [ prompt ] str-vbl ].. 



sep: 



prompt: str-const sep 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Vbl cannot be a DEF function name unless the INPUT LINE statement is inside the multi- 
line DEF that defines the function. 



General Rules 

1 . The default chnl-exp is zero (the controlling terminal). If a chnl-exp is specified, a file must 
be open on that channel with ACCESS READ before the INPUT LINE statement can exe- 
cute. 

2. You can include more than one prompt in an INPUT LINE statement. The first prompt is 
issued for the first vbl, the second prompt for the second vbl, and so on. The sep that 
follows the vbl associated with the prompt has no formatting effect. BASIC always 
advances to a new line when you terminate input with a carriage return. 

3. Sep in the prompt clause determines where the question mark is displayed and where the 
cursor is positioned for input. 

• A comma tells BASIC to skip to the next print zone and display the question mark. For 
example: 

100 INPUT LINE 'NAME' >Y0UR_NAME 

Run 

NAME ? 

• A semicolon tells BASIC to display the question mark next to str-const. For example: 

100 INPUT LINE 'ADDRESS' iADDR* 

Run 

ADDRESS? 
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5. If input comes from a terminal, BASIC displays the contents of str-const, if present, and a 
question mark (?). If you have not specified a str-const, BASIC displays only the question 
mark. The program then waits for data. 

6. If chnl-exp does not correspond to a terminal, BASIC displays only the question mark. 

7. The INPUT LINE statement assigns all input characters including the line terminator(s) to 
str-vbl. Single and double quotation marks, commas, tabs, leading and trailing spaces, or 
other special characters in the string are part of the data. 

8. When a RESUME statement transfers control to an INPUT LINE statement, the INPUT LINE 
statement retrieves a new record regardless of any data left in the previous record. 

9. After a successful INPUT LINE statement, the RECOUNT variable contains the number of 
characters transferred from the file or terminal to the record buffer. 

1 0. If you terminate input text with CTRL IT, BASIC assigns the value to the variable and signals 
"End of file on device" (ERR= 1 1 ) when the next terminal input statement executes. If there 
is no next INPUT, INPUT LINE, or LINPUT statement in the program, the CTRL/Z is passed 
to BASIC as a signal to exit the BASIC environment. BASIC signals "Unsaved changes have 
been made, CTRL/Z or EXIT to exit" if you have made changes to your program. If you 
have not made changes, BASIC exits from the BASIC environment and does not signal an 
error. 

Examples 

S50 INPUT LINE "Type two words"* Z*»"Type your name";N$ 

390 INPUT LINE #4% , REC0RD_STRING$ 
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30.0 ITERATE 

Function 

The ITERATE statement allows you to explicitly reexecute a loop. 

Format 



ITERATE [ label ] 



Syntax Rules 

1 . Label is the label of the first statement of a FOR-NEXT, WHILE, or UNTIL loop 

2. The ITERATE statement can be used only within a FOR-NEXT, WHILE, or UNTIL loop. 

General Rules 

1 . ITERATE is equivalent to an unconditional branch to the current loop's NEXT statement. If 
you supply a label, ITERATE transfers control to the NEXT statement in the specified loop. If 
you do not supply a label, ITERATE transfers control to the current loop's NEXT statement. 

2. Label must conform to the rules for naming variables. 
Examples 

1000 Date.loop: WHILE IX = IX 

GET »1 

ITERATE Date_loop IF Day* <> Today* 
ITERATE Date_loop IF Month* <> Th i s_mon t h* 
ITERATE Date-loop IF Year* <> This_vear* 
PRINT Item* 
NEXT 
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31.0 KILL 

Function 

The KILL statement deletes a disk file, removes the file's directory entry, and releases the file's storage 
space. 

Format 



KILL file-spec 



Syntax Rules 



1 . File-spec can be a quoted string constant, a string variable, or a string expression. It cannot 
be an unquoted string constant. 



General Rules 

1 . The KILL statement marks a file for deletion but does not delete the file until all users have 
closed it. 

2. If you do not specify a complete file-spec, BASIC uses the default device and direc- 
tory. If you do not specify a file version, VAX- J 1 BASIC and BASIC-PLUS-2 on 
RSX-1 1MIM-PLUS systems delete the highest version of the file. 

3. The file-spec must exist or BASIC signals an error. 

4. You can delete a file in another directory if you have access to that directory and privilege 
to delete the file. 

Examples 

200 KILL "TEMP. DAT" 
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32.0 LET 

Function 

The LET statement assigns a value to one or more variables. 

Format 



[LET] vbl,... = exp 



Syntax Rules 

1 . Vbl cannot be a DEF or FUNCTION name unless the LET statement occurs inside that DEF 
block or in that FUNCTION subprogram. 

2. You cannot assign string data to a numeric variable or numeric data to a string variable. 

3. The keyword LET is optional. 

General Rules 

1 . When you assign a value to a subscripted variable, BASIC evaluates the subscripts from left 
to right before evaluating exp and assigning the value. In the following example, line 10 
assigns the value 5 to I, then line 20 assigns the value 2 to A(5) and to I: 

10 LET I = 5 

20 LET A( I) ,1 = 2 

2. The vaiue assigned to a numeric variable is converted to the variable's data type. For 
example, if you assign a floating-point value to an integer variable, BASIC truncates the 
value to an integer. 

3. For dynamic strings, the destination string's length equals the source string's length. 

4. When you assign a value to a fixed-length string variable, the value is left-justified and 
padded with spaces or truncated to match the length of the string variable. 

Examples 

10 LET A = 3,141 

20 A* = "ABCDEFG" 
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33.0 LINPUT 

Function 

The LINPUT statement assigns a string value, without line terminators, from a terminal or terminal- 
format file to a string variable. 

Format 



LINPUT [ chnl-exp, ] [ prompt ] str-vbl [ sep [ prompt ] str-vbl ].. 



sep: 



prompt: str-const sep 



Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Vbl cannot be a DEF function name unless the LINPUT statement is inside the multi-line 
DEF that defines the function. 



General Rules 



The default chnl-exp is zero (the controlling terminal), if you specify a chnl-exp, the file 
associated with that channel must have been opened with ACCESS READ or MODIFY. 

You can include more than one prompt in an INPUT LINE statement. The first prompt is 
issued for the first vbl, the second prompt for the second vbl, and so on. The sep that 
follows the vbl associated with the prompt has no formatting effect. BASIC always 
advances to a new line when you terminate input with a carriage return. 

Sep in the prompt clause determines where the question mark is displayed and where the 
cursor is positioned for input. 

• A comma tells BASIC to skip to the next print zone and display the question mark. For 
example: 

100 LINPUT "NAME" »Y0UR_NAME 

Run 

NAME ? (continued on next page) 
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• A semicolon tells BASIC to display the question mark next to str-const. For example: 

100 LINPUT "ADDRESS" 5ADDR* 

Run 

ADDRESS? 

4. BASIC signals an error if the LINPUT statement has no argument. 

5. If input comes from a terminal, BASIC displays the contents of str-const, if present, and a 
question mark (?). If you have not specified a str-const, BASIC displays only the question 
mark. The program then waits for data. 

6. If chnl-exp does not correspond to a terminal, BASIC displays only the question mark. 

7. The LINPUT assigns all characters except the line terminator(s) to str-vbl. Single and double 
quotation marks, commas, tabs, leading and trailing spaces, or other special characters in 
the string are part of the data. 

8. If the RESUME statement transfers control to a LINPUT statement, the LINPUT statement 
retrieves a new record regardless of any data left in the previous record. 

9. After a successful LINPUT statement, the RECOUNT variable contains the number of bytes 
transferred from the file or terminal to the record buffer. 

10. If you terminate input text with CTRL/Z, BASIC assigns the value to the variable and signals 
"End of file on device" (ERR = 1 1) when the next terminal input statement executes. If there 
is no next INPUT, INPUT LINE, or LINPUT statement in the program, the CTRL/Z is passed 
to BASIC as a signal to exit the BASIC environment. 

Examples 

100 LINPUT "ENTER YOUR LAST NAME" iLas t_name* 
200 LINPUT »2X» Last-name* 
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340 LSET 



Function 



The LSET statement assigns left-justified data to a string variable. LSET does not change the length of 
the destination string variable. 



Format 



LSET str-vbl,... = str-exp 



Syntax Rules 

1 . Str-vbl is the destination string. Str-exp is the string value assigned to str-vbl. 

2. BASIC evaluates str-vbl's subscripts (if present) before evaluating str-exp. 

3. Str-vbl cannot be a DEF function name unless the LSET statement is inside the multi-line 
DEF that defines the function. 

General Rules 

1 . The LSET statement treats all strings as fixed-length. LSET neither changes the length of the 
destination string nor creates new storage. Rather, it overwrites the str-vbl's current storage. 

2. If the destination string is longer than str-exp, LSET left-justifies str-exp and pads it with 
spaces on the right. If smaller, LSET truncates characters from the right of str-exp to match 
the length of str-vbl. 

Examples 

10 LSET ALPHA$='XYZ' 

20 LSET A*» B$ = CODE* + NA_ME* 
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35.0 MAP 



Function 



The MAP statement defines a named area of statically allocated storage called a PSECT, declares data 
fields in the record, and associates them with program variables. 

Format 



MAP (map-nam) { [ data-type ] map-item },... 


map-item: 


num-unsubs-vbl-nam 
num-array-nam ( int-const,... ) 
str-unsubs-vbl-nam [ = int-const ] 




< 


str-array-nam ( int-const,... ) [ = int-const ] ► 




FILL [ ( int-const ) ] [ = int-const ] 






FILL% [ ( int-const ) ] 






FILL$ [ ( int-const ) 1 [ = int-const 1 





Syntax Rules 




,vax; 



1 . Map-nam is global to the program and task. It cannot appear elsewhere in the program unit 
as a variable name. 

2. In VAX-1 1 BASIC, map-nam can consist of from 1 to 31 characters. The first character of 
the name must be an alphabetic character (A through Z). The remaining characters, if 
present, can be any combination of letters, digits (0 through 9), dollar signs ($), periods (.), 
or underscores (_). 

3. In BASIC-PLUS-2, map-nam can consist of from one to six characters. The first character 
must be an alphabetic character (A through Z). The remaining characters, if present, can be 
any combination of letters, digits (0 through 9), dollar signs ($), or periods (.). 

4. Map-item declares the name and format of the data to be stored. 

• Num-unsubs-vbl-nam and num-arr-nam specify a numeric variable or a numeric array. 

• Str-unsubs-vbl-nam and str-arr-nam specify a fixed-length string variable or array. You 
can specify the number of bytes to be reserved for the variable with the = int-const 
clause. The default string length is 16. 

• The FILL, FILL%, and FILL$ keywords allow you to reserve parts of the record buffer 
within or between data elements and to define the format of the storage. Int-const speci- 
fies the number of FILL items to be reserved. The = int-const clause allows you to specify 
the number of bytes to be reserved for string FILL items. Table 21 describes FILL item 
format and storage allocation. 
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Note 

In the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n), for example, represents n elements, not n + 1. 

5. Data-type can be any BASIC data-type keyword or, in VAX-1 7 BASIC, a data type defined 
by a RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2. 

6. When you specify a data-type, all following map-items, including FILL items, are of that 
data type until you specify a new data type. 

7. If you do not specify any data-type, map-items without a data-typing suffix character (% or 
$) take the current default data type and size. 

8. Variable names, array names, and FILL items following a data-type cannot end in a dollar 
sign or percent sign. 

9. Variables and arrays declared in a MAP statement cannot be declared elsewhere in the 
program by any other declarative statements. 



General Rules 



1. BASIC does not execute MAP statements. The MAP statement allocates static storage and 
defines data at compile time. 

2. A program can have multiple MAPs with the same name. The allocation for each MAP 
overlays the others. Thus, data is accessible in many ways. The actual size of the data area 
is the size of the largest MAP. When you link or task-build your program, the size of the 
MAP area is the size of the largest MAP with that name. 

3. Map-items with the same name can appear in different MAP statements with the same 
map-nam only if they match exactly in attributes such as data type, position, and so forth. 
If the attributes are not the same, BASIC signals an error. For example: 



100 MAP (ABC) LONG A* B 

200 MAP (ABC) LONG A, C 

300 MAP (ABC) LONG B» A 

400 MAP (ABC) WORD A. B 



This MAP statement is ualid 

This MAP statement produces an error 

This MAP statement produces an error 



Line 300 causes BASIC to signal the error "variable <name> not aligned in multiple 
references in MAP <name>", while line 400 generates the error "attributes of overlaid 
variable <name< don't match". 

4. The MAP statement should precede any reference to variables declared in it. 

5. Storage space for map-items is allocated in order of occurrence in the MAP statement. 

6. A MAP area can be accessed by more than one program module, as long as you define the 
map-nam in each module that references the MAP. 

7. A COMMON area and a MAP area with the same name specify the same storage area and 
are not allowed in the same program module. 
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8. A MAP named in an OPEN statement's MAP clause is associated with that file. The file's 
records and record fields are defined by that MAP. The size of the MAP determines the 
record size for file I/O, unless the OPEN statement includes a RECORDSIZE clause. 

9. VAX-1 1 BASIC does not initialize variables in the MAP statement. 
10. BASIC-PLUS— 2 initializes MAP variables to zero or a null string. 

Examples 

200 MAP (BUF1) BYTE AGE , STRING EMP.NAME = 20. SINGLE EMP-NUM 

400 MAP <BUF1> BYTE FILL* STRING LAST-NAME = 12, FILL = 8> SINGLE FILL 
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36.0 MAP DYNAMIC 

Function 

The MAP DYNAMIC statement names the variables and arrays whose size and position in a MAP 
buffer can change at run time. BASIC sets all variable and array element pointers to the beginning of 
the MAP buffer when the MAP DYNAMIC statement is processed. 

Format 



MAP DYNAMIC fman-nam\ I F Hata-tvno 1 man-itom \ 



map-item: 



num-unsubs-vbl-nam 
num-array-nam ( int-const,... ) 
str-u nsu bs-vbl-nam 
str-array-nam ( int-const,... ) 



Syntax Rules 

1 . Map-nam is the storage area named in a MAP statement. 

2. Map-item declares the name and data type of the items to be stored in the map buffer. All 
variable pointers point to the beginning of the map buffer until the program executes a 
REMAP statement. 

• Num-unsubs-vbl-nam and num-arr-nam specify a numeric variable or a numeric array. 

• Str-unsubs-vbl-nam and str-arr-nam specify a string variable or array. You cannot specify 
the number of bytes to be reserved for the variable in the MAP DYNAMIC statement. All 

unig Hems nave a uXcu-ia igu i ui iau Jinn uic piugiain cXcLuicS a i\LiVi/-\r Sicuci nci n. 

3. Data-type can be any BASIC data-type keyword or, in VAX-1 1 BASIC, a data type defined 
in the RECORD statement. Data-type keywords, size, range, and precision are listed in 
Table 2 in this manual. 

4. When you specify a data-type, all following map-items are of that data type until you 
specify a new data type. 

5. If you do not specify any data-type, map-items take the current default data type and size. 

6. Variable names and array names following a data-type cannot end in a dollar sign or 
percent sign suffix character. 

7. Variables and arrays declared in a MAP DYNAMIC statement cannot be declared else- 
where in the program by any other declarative statements. 

8. Map-items must be separated with commas. 
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General Rules 

1 . The MAP DYNAMIC statement does not affect the amount of storage allocated to the map 
buffer declared in a previous MAP statement. Until your program executes a REMAP 
statement, all variable and array element pointers point to the beginning of the MAP buffer. 

2. BASIC does not execute MAP DYNAMIC statements. The MAP DYNAMIC statement 
names the variables whose size and position in the MAP buffer can change and defines 
their data type. 

3. If there is no MAP statement in the program unit with the same map-nam specified in the 
MAP DYNAMIC statement, BASIC signals the error "Insufficient space for MAP DYNAMIC 
variables in MAP <name>". 

4. The MAP DYNAMIC statement must lexically precede the REMAP statement or BASIC 
signals the error "MAP variable <name> referenced before declaration". 

Examples 

100 MAP (MY.BUF) STRING DUMMY = 512 

MAP DYNAMIC <MY.BUF) STRING LAST, FIRST, MIDDLE, 8= 

BYTE AGE, STRING EMPLOYER, & 

STRING CHARACTERISTICS 
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3f.U MAmallN (VMA-I I DMOIU/ 

Function 

The MARGIN statement specifies the margin width for a terminal or for records in a terminal-format 
file. 

Format 



MARGIN [ chnl-exp, ] int-exp 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Int-exp specifies the margin width. 

General Rules 

1 . If you do not specify a chnl-exp, BASIC sets the margin on the controlling terminal. 

2. The file associated with chnl-exp must be an open terminal-format file. 

3. BASIC signals the error "Illegal operation" (ERR =141) if the file associated with chnl-exp 
is not a terminal-format file. 

4. If chnl-exp does not correspond to a terminal, and if int-exp is zero, BASIC sets the right 
margin to the size specified by the RECORDS1ZE clause in the OPEN statement, if present. 
If no RECORDSIZE clause is present, BASIC sets the margin to the RMS blocksize. 

5. If chnl-exp is not present or if it corresponds to a terminal, and if int-exp is zero, BASIC sets 
the right margin to the size specified by the RECORDSIZE clause in the OPEN statement, if 
present. If no RECORDSIZE clause is present, BASIC sets the margin to the default terminal 
width. 

6. BASIC prints as much of a specified record as the margin setting allows on one line before 
going to a new line. Numeric fields are never split across lines. 

7. If you specify a margin larger than the channel's recordsize, BASIC signals an error. 

8. The MARGIN statement is in effect only while chnl-exp is open. When you close chnl-exp, 
BASIC returns to the default margin when you reopen the channel. 

Examples 

30 MARGIN *4» 132% 
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38.0 MAT 

Function 

The MAT statement lets you implicitly create and manipulate one- and two-dimensional arrays. You 
can use the MAT statement to assign values to array elements or to redimension a previously dimen- 
sioned array. You can also perform matrix arithmetic operations such as multiplication, addition, and 
subtraction, and other matrix operations such as transposing and inverting matrices. 

Format 



Initialization (Numeric) 
MAT num-array 



CON 

IDN | [ ( int-exp1 [, int-exp2 ] ) ] 

ZER 



Initialization (String) 

MAT str-array = NUL$ [ ( int-exp1 [, int-exp2 ] ) ] 

Array Arithmetic 



MAT num-array1 = num-array2 



num-array3 



* 



Scalar Multiplication 

MAT num-array4 = ( num-exp ) * num-array5 



Inversion and Transposition 



MAT num-array6 



TRN 
INV 



( num-array7 



Syntax Rules 

1 . You cannot use the MAT statement on arrays of more than two dimensions. 

2. In VAX-1 1 BASIC, you cannot use the MAT statement on arrays of data-type DECIMAL or 
on arrays named in a RECORD statement. 

3. When initializing arrays, you can specify the array bounds. Int-exp1 and int-exp2 define 
the upper bounds of the array being implicitly created or the new dimensions of an existing 
array. J 
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4. if you are creating an array, Int-expl and \ui-exp2 cannot exceeu 10. 

• If you do not specify bounds, BASIC creates the array and dimensions it to (10) or 
(10,10). 

• If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASIC signals "Redimensioned array" (ERR =105). 

5. To perform MAT operations on arrays larger than (10,10), create the input and output 
arrays with the DIM statement. 

6. When the array exists, the following rules apply: 

• If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT operations cannot increase the total number of array elements. 

• If you do not specify bounds, BASIC does not redimension the array. 

7. An array passed to a subprogram and redimensioned there by a MAT statement remains 
redimensioned when control returns to the calling program, with two exceptions: 

• When the array is within a RECORD and is passed BY DESC. 

• When the array is passed BY REF. 

Initialization 

1 . CON sets all elements of num-array to one, except those in row and column zero. 

2. IDN creates an identity matrix from num-array. The number of rows and columns in 
num-array must be identical. IDN sets all elements to zero except those on the diagonal 
from num-array(1,1) to num-array(n,n), which are set to one. 

3. ZER sets all array elements to zero, except those in row and column zero. 

4. NUL$ sets all elements of a string array to the null string, except those in row and column 
zero. 

Array Arithmetic 

1. The equals sign ( = ) assigns the results of the specified operation to the elements in 
num-array 1 . 

2. If num-array3 is not specified, BASIC assigns the values of num-array2's elements to the 
corresponding elements of num-array 1 . Num-arrayl must have at least as many rows and 
columns as num-array2. 

3. Use the plus sign ( + ) to add the elements of two arrays. Num-array2 and num-array3 must 
have identical bounds. 

4. Use the minus sign (-) to subtract the elements of two arrays. Num-array2 and num-array3 
must have identical bounds. 

5. Use the asterisk (*) to perform matrix multiplication on the elements of num-array2 and 
num-array3 and to assign the results to num-arrayl . This operation gives the dot product of 
num-array2 and num-array3. All three arrays must be two-dimensional, and the number of 
columns in num-array2 must equal the number of rows in num-array3. BASIC redimen- 
sions num-arrayl to have the same number of rows as num-array2 and the same number of 
columns as num-array 3. 
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Scalar Multiplication 

1. BASIC multiplies each element of num-array5 by num-exp and stores the results in the 
corresponding elements of num-array4. 

Inversion and Transposition 

1. TRN transposes num-array7 and assigns the results to num-array6. If num-array7 has 
m rows and n columns, num-array6 will have n rows and m columns. Both arrays must be 
two-dimensional. 

2. You cannot transpose a matrix to itself: MAT A = TRN (A) is invalid. 

3. INV inverts num-array7 and assigns the results to num-arrayb. Num-array7 must be a two- 
dimensional array that can be reduced to the identity matrix using elementary row opera- 
tions. The row and column dimensions must be identical. 

General Rules 

1 . You cannot increase the number of array elements or change the number of dimensions in 
an array when you redimension with the MAT statement. That is, you can redimension an 
array with dimensions (5,4) to (4,5) or (3,2), but you cannot redimension that array to (5,5) 
or to (10). The total number of array elements includes those in row and column zero. 

2. If an array is named in both a DIM statement and a MAT statement, the DIM statement 
must lexically precede the MAT statement. 

3. MAT statements do not operate on elements in: 1) the zero element (one-dimensional 
arrays) or 2) the zero row or column (two-dimensional arrays). MAT statements use these 
elements to store results of intermediate calculations. Therefore, you should not depend on 
values in row and column zero if your program uses MAT statements. 

Examples 

Initialization (Numeric) 

100 MAT CONMERT = ZER(10,10) 

Initialization (String) 

1000 MAT NA_ME* = NUL$<5,5> 

Array Arithmetic 

2000 MAT NEW.INT = 0LD.INT - RSLT.INT 

Scalar Multiplication 

3000 MAT Z40 = (4,24) * Z 

Inversion and Transposition 

4000 MAT Ql = INV <Z%) 
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39.0 MAT INPUT 

Function 

The MAT INPUT statement assigns values from a terminal or terminal-format file to array elements. 
Format 



MAT INPUT [ chnl-exp, ] { array [ ( int-exp1 [, int-exp2 ])]},. 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. The file associated with chnl-exp must be an open terminal-format file. If chnl-exp is not 
specified, BASIC takes data from the controlling terminal. 

3. You cannot use the MAT INPUT statement on arrays of more than two dimensions. 

4. In VAX-11 BASIC, you cannot use the MAT INPUT statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 

5. Int-expl and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 

6. If you are creating an array, int-exp1 and int-exp2 cannot exceed 10. 

• If you do not specify bounds, BASIC creates the array, dimensions it to (10,10), and 
prompts only for the first array element. 

• If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASiC signais "Redimensioned array" (ERR =105). 

7. To MAT INPUT to arrays larger than (10,10), create the input and output arrays with the 
DIM statement. When the array exists, the following rules apply: 

• If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT INPUT cannot increase the total number of array elements. 

• If you do not specify bounds, BASIC does not redimension the array. 
General Rules 

1. The MAT INPUT statement prompts with a question mark on terminals open on channel 
zero only. 

2. Use commas to separate data elements and a line terminator to end the input of data. Use 
an ampersand before the line terminator to input data on more than one line. 

3. The MAT INPUT statement assigns values by row. That is, it assigns values to all elements 
in row one before beginning row two. 
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4. The MAT INPUT statement assigns the row number of the last data element transferred into 
the array to the system variable, NUM. 

5. The MAT INPUT statement assigns the column number of the last data element transferred 
into the array to the system variable, NUM2. 

6. If there are fewer elements in the input data than there are array elements, BASIC does not 
change the remaining array elements. 

7. If there are more data elements in the input stream than there are array elements, BASIC 
ignores the excess. 

8. Row zero and column zero are not changed. 
Examples 

1000 MAT INPUT EMP.NAME* ( 10 . 10 ) 
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40.0 MAT LINPUT 



Function 



The MAT LINPUT statement receives string data from a terminal or terminal-format file and assigns it 
to string array elements. 

Format 



MAT LINPUT [ chnl-exp, ] { str-array [ ( int-exp1 [, int-exp2 ] ) ] },... 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. You cannot use the MAT LINPUT statement on arrays of more than two dimensions. 

3. In VAX-11 BASIC, you cannot use the MAT LINPUT statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 

4. The file associated with chnl-exp must be an open terminal-format file. If chnl-exp is not 
specified, BASIC takes data from the controlling terminal. 

5. Int-expl and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 

6. If you are creating an array, int-exp) and int-exp2 cannot exceed 10. 

• If you do not specify bounds, BASIC creates the array, dimensions it to (10,10), and 
prompts only for the first array element. 
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bounds exceed (10) or (10,10), BASIC signals "Redimensioned array" (ERR=105). 

7. To MAT LINPUT to arrays larger than (10,10), create the input and output arrays with the 
DIM statement. 

8. When the array exists, the following rules apply: 

• If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT LINPUT cannot increase the total number of array elements. 

• If you do not specify bounds, BASIC does not redimension the array. 

General Rules 

1 . For terminals open on channel zero only, the MAT LINPUT statement prompts with a 
question mark for each string array element, starting with element (1,1). BASIC assigns 
values to all elements of row one before beginning row two. 

2. The MAT LINPUT statement assigns the row number of the last data element transferred 
into the array to the system variable, NUM. 
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3. The MAT LINPUT statement assigns the column number of the last data element transferred 
into the array to the system variable, NUM2. 

4. Typing only a line terminator in response to the question mark prompt causes BASIC to 
assign a null string to that string array element. 

5. MAT LINPUT does not change row and column zero. 
Examples 

400 MAT LINPUT TIME. CARD* ( 10% ) 
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41.0 MAT PRINT 



Function 



The MAT PRINT statement prints the contents of a one- or two-dimensional array on your terminal or 
assigns the value of each array element to a record in a terminal-format file. 

Format 



MAT PRINT [ chnl-exp, ] { array [ ( int-exp1 [, int-exp2 ] ) ] [ sep ] }... 


sep: 


j 





Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. You cannot use the MAT PRINT statement on arrays of more than two dimensions. 

3. In VAX-11 BASIC, you cannot use the MAT PRINT statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 

4. The file associated with chnl-exp must be an open terminal-format file. If you do not 
specify a chnl-exp, BASIC takes data from the controlling terminal. 

5. Int-expl and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 

6. If the array does not exist, the following rules apply: 

• If you do not specify bounds, BASIC creates the array and dimensions it to (10,10). 

• If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASIC prints (10) or (10,10) elements and signals 
"Subscript out of range" (ERR = 55). 

7. When the array exists, the following rules apply: 

• If the specified bounds are smaller than the maximum bounds of a dimensioned array, 
BASIC prints a subset of the array, but does not redimension the array. For example, if 
you use the DIM statement to dimension A(20,20), and then MAT PRINT A(2,2), BASIC 
prints elements (1,1), (1,2), (2,1), and (2,2) only; array A(20,20) does not change. 

• If you do not specify bounds, BASIC prints the entire array. 
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8. Sep determines the output format for the array: 

• If you use a comma, BASIC prints each array element in a new print zone and starts each 
row on a new line. 

• If you use a semicolon, BASIC separates each array element with a space and starts each 
row on a new line. 

• If you do not use a sep character, BASiC prints each array eiement on its own iine. 

9. When you use the MAT PRINT statement to print more than one array, each array name 
except the last must be followed with either a comma or a semicolon. BASIC prints a blank 
line between arrays. 

General Rules 

1 . The MAT PRINT statement does not print elements in row or column zero. 

2. The MAT PRINT statement cannot redimension an array. 

Examples 

500 MAT PRINT »1» TIME. CARD* ( 25 ) 5 
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42.0 MAT READ 

Function 

The MAT READ statement assigns values from DATA statements to array elements. 

Format 



MAT READ { array [ ( int-exp1 [, int-exp2 ] ) ] },... 



Syntax Rules 

1 . You cannot use the MAT READ statement on arrays of more than two dimensions. 

2. In VAX-11 BASIC, you cannot use the MAT READ statement on arrays of data-type 
DECIMAL or on arrays named in a RECORD statement. 

3. /nt-exp7 and int-exp2 define the upper bounds of the array being implicitly created or the 
dimensions of an existing array. 

4. If you are creating an array, mt-expl and int-exp2 cannot exceed 10. 

• If you do not specify bounds, BASIC creates the array and dimensions it to (10,10). 

• If you do specify bounds, BASIC creates the array with the specified bounds. If the 
bounds exceed (10) or (10,10), BASIC signals "Redimensioned array" (ERR =105). 

5. To MAT READ arrays larger than (10,10), create the array with the DIM statement. 

\j, » vuCii li iv, cti i dy C/\i3l3, u ic il/i iwvv ii ig, iuicj ciiJLSiy. 

• If you specify bounds, BASIC redimensions the array to the specified size. However, 
MAT READ cannot increase the total number of array elements. 

• If you do not specify bounds, BASIC does not redimension the array. 
General Rules 

1. The DATA statement(s) must be in the same program unit as the MAT READ statement. 

2. The MAT READ statement assigns data items by row. That is, it assigns data items to all 
elements in row one before beginning row two. 

3. The MAT READ statement does not read elements into row or column zero. 

4. The MAT READ statement assigns the row number of the last data element transferred into 
the array to the system variable, NUM. 
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The MAT READ statement assigns the column number of the last data element transferred 
into the array to the system variable, NUM2. 

If you MAT READ an existing array without specifying bounds, BASIC does not redimen- 
sion the array. If you MAT READ an existing array and specify bounds, BASIC redimen- 
sions the array. 



Examples 

100 MAT READ Z% 
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Function 

The MOVE statement transfers data between a record buffer and a list of variables. 
Format 





TO 








MOVE 


FROM 


chnl-exp, move-item,... 






move-item: 


num-vbl 

num-array ( [,]...) 
str-vbl [ = int-exp ] 


i 




< 


str-array ( [,]... ) [ = int-exp ] 


► 




[ data-type ] FILL [ ( int-exp ) ] [ = 


int-const ] 






FILL% [ ( int-exp ) ] 








FILLS [ ( int-exp ) ] [ = int-exp ] 


* 





Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Move-item specifies the variable or array to which or from which data is to be moved. 

3. Num-vbl and num-array specify a numeric variable or a numeric array. Parentheses indi- 
cate the number of dimensions in a numeric array. The number of dimensions is equai to 
the number of commas plus one. That is, empty parentheses indicate a one-dimensional 
array, one comma indicates a two-dimensional array, and so on. 

4. Str-vbl and str-array specify a fixed length string variable or array. Parentheses indicate the 
number of dimensions in a string array. The number of dimensions is equal to the number 
of commas plus one. You can specify the number of bytes to be reserved for the variable or 
array elements with the = int-exp clause. The default string length for a MOVE FROM 
statement is 16. For a MOVE TO statement, the default is the string's length. 

5. The FILL, FILL%, and FILLS keywords allow you to transfer fill items of a specific data type. 
Table 21 shows FILL item formats, representations, and storage requirements. 

• If you specify a data-type before the FILL keyword, the fill is of that data type. If you do 
not specify a data-type, the fill is of the default data type. Data-type can be any BASIC 
data-type keyword or, in VAX-1 1 BASIC, a data type defined by a RECORD statement. 
Data-type keywords, size, range, and precision are listed in Table 2 in this manual. FILL 
items following a data-type cannot end in a dollar sign or percent sign. 

• Int-exp specifies the number of FILL items to be moved. 



• FILL% indicates integer fill. FILLS indicates string fill. The 
number of bytes to be moved for string FILL items. 



■int-exp clause specifies the 
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Note 

In tnc applicable formats oi Fill, \ini-exp/ represents a repeat count, not an 
array subscript. FILL (n), for example, represents n elements, not n + 1. 

6. You cannot use an expression or function reference as a move-item. 

General Rules 

1. Before a MOVE FROM statement can execute, the file associated with chnl-exp must be 
open and there must be a record in the record buffer. 

2. A MOVE statement neither transfers data to or from external devices, nor invokes the 
system Record Management Services. Instead, it transfers data between user areas. Thus, a 
record should first be fetched with the GET statement before using a MOVE FROM, and a 
MOVE TO should be followed by a PUT or UPDATE statement that writes the record to a 
file. 

3. MOVE FROM transfers data from the record buffer to the move-item. 

4. MOVE TO transfers data from the move-item to the record buffer. 

5. The MOVE statement does not affect the record buffer's size. If a MOVE statement partially 
fills a buffer, the rest of the buffer is unchanged. If there is more data in the variable list 
than in the buffer, BASIC signals "MOVE overflows buffer" (ERR=161). 

6. Each MOVE statement to or from a channel transfers data starting at the beginning of the 
buffer. For example: 

200 MOVE FROM *1%» IX, A* = IX 

In this example, BASIC assigns the first value in the record buffer to l%; the value of l% is 
then used to determine the length of A$. 

7. If a MOVE statement operates on an entire array: 

• BASIC transfers elements of row and column zero (contrast this with the MAT 
statements). 

• The storage size of the array elements and the size of the array determine the amount of 
data moved. A MOVE statement that transfers data from the buffer to a longword integer 
array transfers the first four bytes of data into element (0,0), the next four bytes of data 
into element (0,1), and so on. 

8. If the MOVE TO statement specifies an explicit string length, the following restrictions 
apply: 

• If the string is equal to or longer than the explicit string length, BASIC moves only the 
specified number of characters into the buffer. 

• If the string is shorter than the explicit string length, BASIC moves the entire string and 
pads it with spaces to the specified length. 

9. BASIC does not check the validity of data during the MOVE operation. 
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990 MOVE FROM *UZ , RUN9X » HITS*. » ERRORS* > RBIX. BAT.AVERAGE 
100 MOVE TO »9%, FILL$ = 10%. A$ = 101. B* = 301 t C* = 21 
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44.0 NAME AS 

Function 

The NAME AS statement changes the name of a specified file. 

Format 



NAME file-sped AS file-spec2 



Syntax Rules 

1. File-sped and file-sped must be string expressions. 

2. There is no default for file type in file-sped or file-sped. If the file to be renamed has a file 
type, file-sped must include both the file name and the file type. If you specify only a file 
name, BASIC searches for a file with no file type. If you do not specify a file type for 
file-sped, BASIC names the file, but does not assign a file type. 

General Rules 

1 . If the file specified by file-sped does not exist, BASIC signals "Can't find file or account" 
(ERR = 5). 

2. In VAX-11 BASIC and BASIC-PLUS-2 on RSX-11 M / M-PLUS systems, file version num- 
bers are optional. BASIC renames the highest version of file-sped if you do not specify a 
version number. 

3. in VAX-11 BASIC and BASIC-PLUS-2 on RSX-1 1 M I M-PLUS systems, if you use the 
NAME AS statement on an open file, BASIC does not rename the file until you close it. 

Examples 

400 NAME "OUT. DAT" AS "RERUN.DAT" 
500 NAME 0LD_FILE$ AS NEW_FILE$ 
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Function 

The NEXT statement marks the end of a FOR, UNTIL, or WHILE loop. 

Format 



NEXT [ num-unsubs-vbl ] 



Syntax Rules 

1. Num-unsubs-vbl is required in a FOR loop and must correspond to the num-unsubs-vbl 
specified in the FOR statement. 

2. Num-unsubs-vbl is not allowed in an UNTIL or WHILE loop. 

General Rules 

1. Each NEXT statement must have a corresponding FOR, UNTIL, or WHILE statement or 
BASIC signals an error. 

Examples 

100 NEXT 1% 
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46.0 NOMARGIN (VAX-11 BASIC) 

Function 

The NOMARGIN statement removes the right margin limit set with the MARGIN statement for a 
terminal or a terminal-format file. 

Format 



NOMARGIN [ chnl-exp ] 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

General Rules 

1 . When you specify NOMARGIN, the right margin is set to 1 32. 

2. Chnl-exp, if specified, must be an open terminal-format file or a terminal. 

3. If you do not specify a chnl-exp, BASIC sets the margin on the controlling terminal to 1 32. 

4. The NOMARGIN statement applies to the specified channel only while the channel is 
open. If you close the channel and then reopen it, BASIC uses the default margin of 72. 

Examples 

1000 NOMARGIN *2% 
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Function 



After BASIC executes an ON ERROR GO BACK in a subprogram or DEF, control transfers to the 
calling program when an error occurs. 

Format 



ONERROR 

ON ERROR 1 GO BACK 



Syntax Rules 

None. 

General Rules 

1 . The ON ERROR GO BACK statement is the default error handler for DEF functions. 

2. An ON ERROR GO BACK statement executed in the main program is equivalent to an 
ON ERROR GOTO statement. 

3. If a main program calls a subprogram named SUB1, and SUB1 calls the subprogram 
named SUB2, an ON ERROR GO BACK statement executed in SUB2 transfers control to 
SUB1 when an error occurs in SUB2. If SUB1 also has executed an ON ERROR 
GO BACK statement, BASIC transfers control to the main program's error handling 
routine. 

4. If there is no error outstanding, execution of an ON ERROR GO BACK statement causes 
subsequent errors to return control to the calling program's error handler. 

5. If there is an error outstanding, execution of an ON ERROR GO BACK statement immedi- 
ately transfers control to the calling program's error handler. 

6. The ON ERROR GO BACK statement remains in effect until the program unit completes 
execution or until BASIC executes another ON ERROR statement. 

Examples 

100 SUB LIST (A*) 

ON ERROR GOTO 19000 
OPEN A* FOR INPUT AS FILE #1 
400 LINPUT *1 » B$ 

PRINT B* 
BOO GOTO aoo 

! 
! 
! 
19000 IF (ERR = 11%) AND (ERL = 400%) 
THEN CLOSE *1% 
RESUME 32767 
ELSE ON ERROR GO BACK 
327B7 SUBEND 
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48.0 ON ERROR GOTO 

Function 

The ON ERROR GOTO statement transfers program control to a specified line or label in the current 
program unit when an error occurs. 

Format 





ONERROR 
ON ERROR 




GOTO | 
GOTO j target 



Syntax Rules 

1 . Target must exist in the same program unit as the ON ERROR GOTO statement. 

2. If an ON ERROR GOTO is in a DEF, target must also be in that function definition. 

General Rules 

1 . Execution of an ON ERROR GOTO statement causes subsequent errors to transfer control 
to the specified target. 

2. The ON ERROR GOTO statement remains in effect until the program unit completes 
execution or until BASIC executes another ON ERROR statement. 

3. BASIC does not allow recursive error handling. If a second error occurs during execution of 
an error-handling routine, control passes to the BASIC error handler and the program stops 
executing. 

Examples 

500 ON ERROR GOTO 9999 

000 ON ERROR GOTO YES.ROUTINE 
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49.0 ON ERROR GOTO 

Function 

The ON ERROR GOTO statement disables user error handling and passes control to the BASIC 
error handler when an error occurs. 

Format 




Syntax Rules 

None. 

General Rules 



1 . If an error is outstanding, execution of an ON ERROR GOTO statement immediately 
transfers control to the BASIC error handler. 

2. If there is no error outstanding, execution of an ON ERROR GOTO statement causes 
subsequent errors to transfer control to the BASIC error handler. 



Examples 



19000 



ON ERROR GOTO 
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50.0 ON GOSUB 

Function 

The ON GOSUB statement transfers program control to one of several subroutines, depending on the 
value of a control expression. 

Format 



ON int-exp GOSUB target,... [ OTHERWISE target ] 



Syntax Rules 

1 . Target must exist in the current program unit. 

2. Control cannot be transferred into a statement block (such as FOR/NEXT, UNTIL/NEXT, 
WHILE/NEXT, DEF/END DEF, or SELECT/END SELECT). 

3. You can use the ON GOSUB statement in a statement block if ON GOSUB and all its 
targets are inside that statement block. 

General Rules 

1. Int-exp determines which target BASIC selects as the GOSUB argument. If int-exp equals 
one, BASIC selects the first target. If int-exp equals two, BASIC selects the second target, 
and so on. 

2. If there is an OTHERWISE clause, and if int-exp is less than one or greater than the number 
of targets in the list, BASIC selects the target of the OTHERWISE clause. 

3. If there is no OTHERWISE clause, and if int-exp is less than one or greater than the number 
of targets in the list, BASIC signals "ON statement out of range" (ERR = 58). 

4. If a target specifies a nonexecutable statement, BASIC transfers control to the first execut- 
able statement that lexically follows the target. 

Examples 

150 ON CONTROL! GOSUB 100.200.300.400 

ZOO ON AX GOSUB 10000 . 1 2000 . 14000 OTHERWISE 21000 
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51.0 ON GOTO 

Function 

The ON GOTO statement transfers program control to one of several lines, depending on the value of 
a control expression. 

Format 



GOTO 
ON int-exp / GOTO 



target ,... [ OTHERWISE target ] 



Syntax Rules 

1 . Target must exist in the current program unit. 

2. Control cannot be transferred into a statement block (such as FOR/NEXT, UNTIL/NEXT, 
WHILE/NEXT, DEF/END DEF, SELECT/END SELECT). 

3. You can use the ON GOTO statement in a statement block if ON GOTO and all its targets 
are inside that statement block. 

General Rules 

1. Int-exp determines which line number BASIC selects as the GOTO argument. If int-exp 
equals one, BASIC selects the first target. If int-exp equals two, BASIC selects the second 
target, and so on. 

2. If there is an OTHERWISE clause, and if int-exp is less than one or greater than the number 
of targets in the list, BASIC transfers control to the target of the OTHERWISE clause. 

3. If there is no OTHERWISE clause, and if int-exp is less than one or greater than the number 
of line numbers in the iist, BASIC signals "ON statement out of range" (ERR = 58). 

4. If a target specifies a nonexecutable statement, BASIC transfers control to the first execut- 
able statement that lexically follows the target. 

Examples 

330 ON INDEX! GOTO 700.800,900 OTHERWISE 1000 
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52.0 OPEN 



Function 



The OPEN statement opens a file for processing. It transfers user-specified file characteristics to 
Record Management Services and verifies the results. 

Format 





" FOR INPUT 




OPEN file-sped 


FOR OUTPUT _ 


AS [ FILE ] chnl-expl [, open-clause ]... 


open-clause: 




1 VIRTUAL j 
I UNDEFINED 1 






- 


[ ORGANIZATION ] 1 INDEXED > 
/ SEQUENTIAL j 


STREAM 
VARIABLE 


• 






\ RELATIVE / 


FIXED 






f -^ 






/ NONE 










J READ 








' 


ALLOW j WRITE 
1 MODIFY 


• 


- 






/ APPEND 


"* 








1 READ 










ACCESS I WRITE 
1 MODIFY 
1 SCRATCH 


1 


► 






f 


LIST 








• 


RECORDTYPE 

• 


FORTRAN 

NONE 

ANY 


> 


• 




) 



(continued on next page) 
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RECORDSIZE int-exp1 

FILESIZE int-exp2 

WINDOWSIZE int-exp3 

TEMPORARY 

CONTIGUOUS 

MAP map-nam 

CONNECT chnl-exp2 

BUFFER int-exp4 

USEROPEN Func-nam 

DEFAULTNAME file-spec2 

EXTENDSIZE int-exp5 

MODE int-exp6 

CLUSTERSIZE int-exp7 

BLOCKSIZE int-exp8 

NOREWIND 

NOSPAN 

SPAN 

BUCKETSIZE int-exp9 

PRIMARY [ KEY ] key [ DUPLICATES ] 

ALTERNATE [ KEY ] key [ DUPLICATES ] 

UNLOCK EXPLICIT 



CHANGES 



Key: 



str-unsubs-vbl 

int-unsubs-vbl 

decimal-unsubs-vbl 

( str-unsubs-vbl1 ,... str-unsubs-vbl8 



(Except on RSTS/E) 



(Except on RSTS/E) 

(BASIC-PLUS-2 only) 

(BASIC-PLUS-2 on RSTS/E only) 

(Sequential files) 

(Sequential files) 

(Sequential files) 

(Sequential files) 

(Relative and Indexed files) 

(Indexed files) 

(Indexed files) 

(VAX-1 1 BASIC only) 



February 1984 
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1 . File-specl specifies the file to be opened and associated with chnl-exp] . It can be any valid 
string expression and must conform to your system's rules for file specifications. BASIC 
passes these values to RMS without editing, alteration, or validity checks. 

• VAX-1 1 BASIC does not supply any default file specifications unless you include the 
DEFAULTNAME clause in the OPEN statement. 

• BASIC-PLUS-2 supplies the device as a default. If a device has been supplied in a 
previous OPEN statement, that device is used as the default. If there is no previous 
device, SY: is supplied as the default device. There is no default for the file type unless 
you include the DEFAULTNAME clause in the OPEN statement. 

2. The FOR clause determines how BASIC opens a file. 

• If you open a file FOR INPUT, the file must exist or BASIC signals an error. 

• If you open a file FOR OUTPUT, BASIC creates the file if it does not exist. If the file does 
exist, VAX-1 1 BASIC and BASIC-PLUS-2 on RSX-1 1M/M-PLUS systems create a new 
version of the file. BASIC-PLUS-2 on RSTS/E systems overwrites the existing file. 

• If you do not specify either FOR INPUT or FOR OUTPUT, BASIC tries to open an existing 
file. If there is no such file, BASIC creates one. 

3. Chnl-exp is a numeric expression that specifies a channel number to be associated with 
file-spec. It can be preceded by an optional pound sign (#). 

• In VAX-1 1 BASIC, chnl-exp must be in the range 1 to 99. 

• In BASIC-PLUS-2, chnl-exp must be in the range 1 to 12. 

4. The ORGANIZATION clause specifies the file organization. When present, it must precede 
all other clauses. When your OPEN statement has ORGANIZATION SEQUENTIAL 
RELATIVE, or INDEXED, you get an RMS file. 

• On VAX/VMS and RSX-1 1M/M-PLUS systems, you get a terminal-format file when you 
omit the ORGANIZATION clause entirely. Terminal-format files are implemented as 
RMS sequential variable files and store ASCII characters in variable-length records. Car- 
riage control is performed by the operating system; the record does not contain carriage 
returns or line feeds. You use essentially the same syntax to access terminal-format files 
as when reading from or writing to the terminal (INPUT and PRINT). 

• On RSTS/E systems, when you omit the ORGANIZATION clause, you get a terminal- 
format file that is a native mode RSTS/E ASCII stream file. RSTS/E ASCII stream files 
contain embedded carriage control characters. That is, carriage return and line feed 
characters are part of the record. See BASIC on RSTS/E Systems for more information on 
RSTS/E native mode files. 

5. In the USEROPEN clause, func-nam must be a separately compiled FUNCTION subpro- 
gram and must conform to FUNCTION statement rules for naming subprograms. 

6. The key specified in the PRIMARY KEY or ALTERNATE KEY clause must be declared in the 
MAP statement referenced by the OPEN statement. 
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General Rules 

1 . The OPEN statement does not retrieve records. 

2. Channel zero, the terminal, is always open. If you try to open channel zero, VAX-1 1 
BASIC signals the error "Illegal I/O channel" (ERR = 46) and BASIC-PLUS-2 signals "I/O 
channel already open at line <number>". 

3. A statement that accesses a file cannot execute until you open that file and associate it with 
a chnl-exp. 

4. If a program opens a file on a channel already associated with an open file, BASIC closes 
the previously opened file and opens 



U iv 



5. The FOR clause does not specify how your program can use the file or how others can 
share it. The ACCESS clause specifies how you use the file and the ALLOW clause specifies 
how the file is shared. 

6. The ALLOW clause determines how other users can access the file: 

• ALLOW NONE lets no other users access the file. This is the default if any ACCESS other 
than READ is specified. 

• ALLOW READ lets other users have READ access to the file. This is the default for 
ACCESS READ. 

• ALLOW WRITE lets other users have WRITE access to the file. 

• ALLOW MODIFY lets other users have unlimited access to the file. 

7. The ACCESS clause determines how the program can use the file: 

• ACCESS READ allows only FIND, GET, or other input statements on the file. The OPEN 
statement cannot create a file if the ACCESS READ clause is specified. 

• ACCESS WRITE allows only PUT, UPDATE, or other output statements on the file. 

• ACCESS MODIFY aiiows any I/O statement except SCRATCH on the file. ACCESS 
MODIFY is the default. 

• ACCESS SCRATCH allows any I/O statement valid for a sequential or terminal-format 
file. 

• ACCESS APPEND is the same as ACCESS WRITE for sequential files, except that BASIC 
positions the file pointer after the last record when it opens the file. You cannot use 
ACCESS APPEND on relative or indexed files. 

8. The RECORDTYPE clause can be used only with RMS files. It specifies the file's record 
attributes: 

• LIST specifies implied carriage control, <CR> <LF> in BASIC-PLUS-2, and <CR> in 
VAX-1 1 BASIC. This is the default for all file organizations except VIRTUAL. 

• FORTRAN specifies a control character in the record's first byte. 

• NONE specifies no attributes. This is the default for VIRTUAL files. 

• ANY specifies a match with any file attributes when opening an existing file. If you create 
a new file, ANY is treated as LIST for all organizations except VIRTUAL. For VIRTUAL, it 
is treated as NONE. 
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9. The RECORDSIZE clause specifies the file's record size: 

• Fnr ORGANIZATION FIVFD int-f>vr>1 cnprifipc th*» civo <->f all rarnrAc 

• For ORGANIZATION VARIABLE, int-exp1 specifies the size of the largest record. 

• If you specify both a RECORDSIZE and a MAP clause, the RECORDSIZE clause overrides 
the record size set by the MAP clause. If you specify a MAP but no RECORDSIZE, the 
record size is equal to the MAP size. If there is no MAP, the RECORDSIZE clause 
determines the record size. If there is no MAP or RECORDSIZE specified, BASIC uses the 
default record size for the file organization when creating the file. When a program 
opens an existing file, BASIC uses the file's record size. 

• When creating SEQUENTIAL files, BASIC supplies a default record size of 132. 

• The record size is always 512 for VIRTUAL files unless you specify a RECORDSIZE. 

• If you do not specify a RECORDSIZE clause when opening an existing file, BASIC 
retrieves the record size value from the file. If you open a new file of ORGANIZATION 
RELATIVE and do not specify a RECORDSIZE clause, BASIC signals "Bad recordsize 
value on OPEN" (ERR = 1 48). 

1 0. The FILESIZE clause lets you pre-extend a new file to a specified size. The value of int-exp2 
is the initial allocation of disk blocks. The FILESIZE clause has no effect on an existing file. 

11. Int-exp3 in the WINDOWSIZE clause lets you specify the number of block retrieval 
pointers you want to maintain in memory for the file. Retrieval pointers are associated with 
the file header and point to contiguous blocks on disk. By keeping retrieval pointers in 
memory, you can reduce the I/O associated with locating a record, as the operating 
system does not have to access the file header for pointers as frequently. The number 
of retrieval pointers in memory at any one time is determined by the system default 
or by the WINDOWSIZE clause. The usual default number of retrieval pointers on 
RSX-1 1M/M-PLUS and VAX /VMS systems is seven. 

• On VAX/VMS systems, a value of specifies the default number of retrieval pointers. A 
value of 255 means to map the entire file, if possible. Values between 128 and 254, 
inclusive, are reserved. 

• On RSX-1 1M/M-PLUS systems, you can specify up to 127 retrieval pointers. 

• On RSTS/E systems the number of pointers in a window block is fixed at seven. Thus, 
you cannot use the WINDOWSIZE clause. You can, however, use the CLUSTERSIZE 
clause to increase the number of contiguous blocks mapped by one retrieval pointer. 

12. The TEMPORARY clause causes BASIC to delete the output file as soon as the program 
closes it. 

13. The CONTIGUOUS clause causes RMS to try to create the file as a contiguous sequence of 
disk blocks in BASIC-PLUS-2 and as a contiguous-best-try sequence of disk blocks in 
VAX-1 1 BASIC. The CONTIGUOUS clause does not affect existing files or nondisk files. 
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1 a t-u~ \^ad ^u,,^ cncrifioc that a nrpvini k!v Hprhrpd man-nam is associated with the file's 
record buffer. The MAP clause determines the record buffer's address and length unless 
overridden by the RECORDSIZE clause. 

• The size of the largest MAP with the same map-nam in the current program unit becomes 
the file's record size if the OPEN statement does not include a RECORDSIZE clause. 

• If there is no MAP clause, the record buffer space that BASIC allocates is not directly 
accessible. Thus, MOVE statements are needed to access data in the record buffer. 

• You must have a MAP clause when creating an indexed file; you cannot use KEY clauses 
without MAP statements since keys serve as offsets into the buffer. 

15. The BUFFER clause can be used with all file organizations except UNDEFINED. For 
RELATIVE and INDEXED files, int-exp4 specifies the number of device or file buffers Rec- 
ord Management Services uses for file processing. For SEQUENTIAL files, int-exp4 speci- 
fies the size of the buffer; for example, BUFFER 8 for a SEQUENTIAL file sets the buffer size 
to eight 512-byte blocks. 

16. The USEROPEN clause lets you open a file with your own FUNCTION subprogram. 
Func-nam must conform to the FUNCTION statement rules for naming subprograms. 
BASIC calls the user program after it fills the FAB (File Access Block), the RAB (Record 
Access Block), and the XABs (Extended Attribute Blocks). The subprogram must issue the 
appropriate RMS calls, including $OPEN and $CONNECT, and return the RMS status as 
the value of the function. See the BASIC User's Guide for more information on the 
USEROPEN routine. 

1 7. The DEFAULTNAME clause lets you supply a default file specification. If file-spec! is not a 
complete file spec, file-spec2 in the DEFAULTNAME clause supplies the missing parts. For 
example: 

10 INPUT "FILE NAME"5FNAM$ 
20 OPEN FNAM$ FOR INPUT AS FILE *Ut & 

DEFAULTNAME "DB2:.DAT" 

If you type "ABC" for the file name, BASIC tries to open DB2:ABC.DAT. BASIC-PLUS-2 
allows DEFAULTNAME for RMS files only. 

18. The EXTENDSIZE clause lets you specify the increment by which Record Management 
Services extends a file after its initial allocation is filled. The value of int-exp5 is in 
512-byte disk blocks. 

19. The BLOCKSIZE clause specifies the physical blocksize of magnetic tape files. The value of 
int-exp8 is the number of records in a block. Thus, the block size in bytes is the product of 
the RECORDSIZE and the BLOCKSIZE value. The default BLOCKSIZE is one record. 

20. The NOREWIND clause controls tape positioning on magnetic tape files. If you specify 
neither ACCESS APPEND nor NOREWIND, the OPEN statement positions the tape at its 
beginning and then searches for the file. 

21 . The NOSPAN clause specifies that sequential records do not cross block boundaries. SPAN 
specifies that records can cross block boundaries. SPAN is the default. This clause does not 
affect nondisk files. 

February 1984 BASIC Reference Manual 243 



OPEN 



22. 



23. 



d^c B u UC , KETS J5 E Cla , U$e apP ' ieS ° nly t0 relative and indexed files - !t specifies the size of an 
RMS bucket. The value of int-exp9 is the number of records in a hurkPt The default - "re 
record. ' ■ ■- ~ . 

pSLTJvCcv K u Y daUSe ' etS y ° U Specify an indexed file ' s ke V- You m ^st specify a 
PRIMARY KEY when opening an indexed file. The ALTERNATE KEY clause lets you specify 
up to 254 alternate keys. The ALTERNATE key clause is optional. 

• RMS creates one index list for each PRIMARY and ALTERNATE key you specify These 
indexes are part of the file and contain pointers to the records. Each key you specify 
corresponds to a sorted list of record pointers. 

• The keys you specify determine the order in which records in the file are stored All keys 
must be variables declared in the file's corresponding MAP statement. The position of the 
key in the MAP statement determines its position in the record. The data type and size of 
the key are as declared in the MAP statement. 

• A key can be an unsubscripted string or WORD variable in BASIC-PLUS-2 and an 
unsubscnpted string, WORD, LONG, or packed decimal variable in VAX-// BASIC. 

• You can also create a segmented index key for string keys by separating the string 
variable names with commas and enclosing them in parentheses. You can then reference 
a segment of the specified key by referencing one of the string variables instead of the 
entire key. A string key can have up to eight segments. 

• The order of appearance of keys determines key numbers. The PRIMARY KEY which 
must appear first, is key zero. The first ALTERNATE KEY is one, and so on. 

• DUPLICATES in the PRIMARY and ALTERNATE key clauses specifies that two records 
can have the same key value, if you do not specify DUPLICATES, the key value must be 
unique in all records. 

• CHANGES in the ALTERNATE key clause specifies that you can change the value of an 
alternate key when updating records. If you do not specify CHANGES when creating the 
file, you cannot change the value of a key. You cannot specify CHANGES with the 
PRIMARY KEY clause. 




v vax> VAX-11 BASIC 
1. 



2. 



If you open a terminal-format file with RECORDTYPE NONE, you must explicitly insert 
carriage control characters into the records your program writes to the file. 

When you PRINT to a terminal-format file, you must supply a RECORDSIZE if the margin is 

1°^™™, 7 d C 1 h f. raCterS - F ° r eXample ' if yOU want t0 PRINT a 1 32-character line, specify 
RECORDSIZE 1 32 or use the MARGIN and NOMARGIN statements. 

The CONTIGUOUS clause does not guarantee that the file will occupy a contiguous disk 
area. If RMS can locate the file in a contiguous area, it will do so. However, if there is not 
enough free contiguous space for a file, RMS allocates the largest possible contiguous areas 
and does not signal an error. See the VAX-1 1 RMS User's Guide for more information on 
contiguous disk allocation. 
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4. The CONNECT clause permits multiple record streams to be connected to the file. 

• The CONNECT clause must specify an INDEXED file already opened on chnl-exp2 with 
the primary OPEN statement. You cannot connect to a connected channel, only to the 
initially opened channel. You can connect more than one stream to an open channel. 

• All clauses of the two files to be connected must be identical except MAP, 
CONNECT, and USEROPEN. 

5. VAX-1 1 RMS does not allow the EXTENDSIZE clause for relative and indexed files. 

6. IT you specny N^Klvviinu, tne wrciN staiemeni dues nui pumuuh me id|jc. iuui (jiugiam 
can search for records from the current position. 

7. The ALLOW clause can be used in the OPEN statement to specify file sharing of relative, 
indexed, sequential, and virtual files. But for sequential and virtual files, VAX-77 RMS 
restricts file sharing to files with fixed-length, 512-byte records. It does not allow the 
sharing of sequential files with variable-length records (the default), or of virtual files with 
recordsizes other than 512. 

8. The UNLOCK EXPLICIT clause allows you to explicitly lock records with GET and FIND 
statements. 

• The type of lock you impose on a record with GET or FIND remains in effect until you 
explicitly unlock the record or file with a FREE or UNLOCK statement or until you close 
the file. 

• If you specify UNLOCK EXPLICIT, and do not impose a lock on a record with GET or 
FIND, BASIC imposes the ALLOW NONE lock by default and the next GET or FIND does 
not unlock the previously locked record. 

• You must open a file with UNLOCK EXPLICIT before you can lock records with GET and 

rilNU bLdiemerilS. 06c me scluui is uii vjl i anu i iiNl-' iii lino manual anu v^i lapici u in 

BASIC on VAX/VMS Systems for more information on explicit record locking and unlock- 
ing. 

9. KEY clauses are optional for existing files if the keys in the file match BASIC defaults. If you 
do specify a key, it must match a key in the file. 

BASIC-PLUS-2 



BP2 



1. The ORGANIZATION SEQUENTIAL STREAM clause specifies an RMS sequential stream 
file. 

2. On RSTS/E systems, you can create both RMS sequential stream and RSTS/E ASCII stream Trsts) 
files: 

• If you specify ORGANIZATION SEQUENTIAL STREAM, the file is RMS sequential 
stream. 

• If you omit the ORGANIZATION clause entirely, the file is RSTS/E ASCII (that is, a 
RSTS/E terminal-format file). 

3. If you specify a CONTIGUOUS clause and there is not enough free contiguous space, RMS 
signals an error. 
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4. The CONNECT clause in BASIC-PLUS-2 establishes additional record access streams for 
RMS files that allow your program to process more than one record of a file at the same 
time. Each stream represents an independent and concurrently active sequence of record 
operations. 

• The CONNECT clause must specify a RELATIVE or INDEXED file already open on 
chnl-exp2. 

• Each CONNECT established in a secondary OPEN statement uses another I/O channel. 
Because there are 12 I/O channels available, you can have a maximum of 12 connects 
to a file. 

• All clauses in the secondary OPEN statements must be identical except MAP CON- 
NECT, and USEROPEN. 

•BASIC-PLUS-2 signals the error "Invalid file option" (ERR=139) if your program 
attempts to connect to a record stream that is already connected to another stream. 

5. BASIC-PLUS-2 provides the MODE clause for non-RMS file operations. Int-exp6 specifies 
a MODE value. 

• On RSX-1 1 M I M-PLUS systems, MODE is ignored except when your program is doing 
device-specific I/O to a magnetic tape. In this case, you can use MODE to set the tape 
density. In all other cases, RSX-1 1 M I M-PLUS systems ignore the MODE value. See 
BASIC on RSX-1 1M I M-PLUS Systems for information on MODE values. 

(rots) • On RSTS/E systems, MODE values affect only native-mode files, not RMS files. Further, 

MODE values have different meanings depending on the context in which you use them! 
This is because other pieces of software scan the MODE value to see which bits are set. 
For example, bit 14 may have one meaning to the RSTS/E terminal driver, another 
meaning to the file processor, and a third meaning to the diskette device driver. See 
BASIC on RSTS/E Systems for information on MODE values. 

6. BASIC-PLUS-2 on RSTS/E systems does not support the EXTENDSIZE clause. 

7. On RSTS/E systems, you can specify the smallest amount of contiguous disk space to be 
allocated when an RMS or RSTS/E native-mode file's present allocation is exhausted. You 
do this with the CLUSTERSIZE clause. Int-exp7 must be a power of two. For example, a 
CLUSTERSIZE of eight means that each time the file requires more disk space, the RSTS/E 
operating system must have at least eight contiguous disk blocks to allocate. If the disk is 
fragmented, there may be no eight-block clusters, and BASIC-PLUS-2 signals the error 
"No room for user on device". 

The default size of the clusters is a disk pack parameter set when the disk pack is 
initialized or mounted. This parameter, called a CLUSTER (of 51 2-byte blocks), becomes 
the default CLUSTERSIZE (the smallest amount of disk space that can be allocated for any 
file operations on that disk pack). 

The CLUSTERSIZE clause does not affect the number of blocks read or written. It speci- 
fies only the smallest amount of disk space that can be allocated to a file. 

VAX-1 1 BASIC and BASIC-PLUS-2 on RSX-1 1MI M-PLUS systems do not support the 
CLUSTERSIZE clause; however, the EXTENDSIZE clause serves a similar function. 






• 



• 
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If vnn snprifv NOREWIND. the OPEN FOR OUTPUT statement positions the tape at the 
logical end of the tape. The program can then write records. The OPEN FOR INPUT 
statement searches for the specified file without rewinding. If the file is not found, BASIC 
rewinds the tape and searches for the file from the start of the tape. If the file is still not 
found, BASIC signals the error "File not found". 



Examples 

100 OPEN "INPUT, DAT" FOR INPUT AS FILE *a , & 

ORGANIZATION SEQUENTIAL FIXED* & 

RECORDSIZE ZOO » & 

MAP ABC* & 
ALLOW MODIFY » ACCESS MODIFY 

ZOO OPEN Newfile* FOR OUTPUT AS FILE *3 , & 

ORGANIZATION INDEXED* & 

MAP Emp.name * & 

DEFAULTNAME "DB2:.DAT"> & 

PRIMARY KEY Last$ DUPLICATES. 8= 
ALTERNATE KEY First* CHANGES 



100 MAP (SEGKEY) STRING LAST.NAME = 15. 8= 

FIRST.NAME = 15. MI = 1 

200 OPEN "NAMES, IND" FOR OUTPUT AS FILE #1. & 

ORGANIZATION INDEXED. &= 

PRIMARY KEY (LAST.NAME. FIRST.NAME. MI), & 

MAP SEGKEY 
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53.0 OPTION 

Function 

The OPTION statement allows you to set compilation qualifiers such as default data type, size, and 
scale factor. In VAX-1 1 BASIC, you can also set compilation conditions such as subscript checking, 
overflow checking, decimal rounding, and setup in a source program. The defaults affect only the 
program module in which the OPTION statement occurs. 

Format 



OPTION option-clause,... 



option-clause: 



type-clause: 



size-clause: 



size-item: 



int-clause: 



real-clause: 



active-clause: 



/ TYPE = type-clause 
SIZE = size-clause 
SCALE = int-const 

(ACTIVE 
INACTIVE 

INTEGER 
REAL 
EXPLICIT 
DECIMAL 



= active-clause 



{VAX-11 BASIC only) 
(VAX-11 BASIC only) 



(VAX-1 1 BASIC only) 



(VAX-11 BASIC only) 



size-item 
(size-item,...) 



INTEGER int-clause 
REAL real-clause 
DECIMAL (d,s) 



BYTE 

WORD 

LONG 



SINGLE 

DOUBLE 

GFLOAT j (VAX-11 BASIC only) 

HFLOAT ) (VAX-1 1 BASIC only) 

active-item 
(active-item,... 
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active-item: 



INTEGER OVERFLOW 

DECIMAL OVERFLOW 

SETUP } (all VAX-1 1 BASIC only) 

DECIMAL ROUNDING 

SUBSCRIPT CHECKING 




Syntax Rules 

1 . Option-clause specifies the compilation qualifiers to be in effect for the program module. 

• Type-clause sets the default data type for variables not explicitly declared in the program 
module. You can specify only one type-clause in a program module. 

• Size-clause sets the default data subtypes for floating-point, integer, and (VAX-1 1 BASIC 
only) packed decimal data. Size-item specifies the data subtype you want to set. You can 
specify an INTEGER and /or REAL size-item in BASIC-PLUS-2 and an INTEGER, REAL, 
and /or DECIMAL size-item in VAX-1 1 BASIC. Multiple size-items in an OPTION state- 
ment must be enclosed in parentheses and separated by commas. 

• SCALE controls the scaling of double precision floating-point variables. Int-const speci- 
fies the power of 10 you want as the scaling factor. It must be an integer from to 6, 
inclusive, or BASIC signals an error. See the SCALE command in Section II of this manual 
for more information on scaling. 

• In VAX-1 1 BASIC, active-clause specifies the decimal rounding, integer and decimal <vax) 
overflow checking, setup, and subscript checking conditions you want in effect for the 
program module. Active-item specifies the conditions you want to set. Multiple 
active-items in an OPTION statement must be enclosed in parentheses and separated by 
commas. 

2. You can have more than one option in an OPTION statement, or you can use multiple 
OPTION statements in a program module. However, each OPTION statement must lexi- 
cally precede all other source code in the program module, with the exception of comment 
fields, REM, SUB, FUNCTION, and OPTION statements. 

General Rules 

1. OPTION statement specifications apply only to the program module in which the state- 
ment appears and affect all variables in the module, including SUB and FUNCTION 
parameters. 

2. BASIC signals an error in the case of conflicting options. For example, you cannot specify 
more than one type-clause or SCALE factor in the same program unit. 

3. If you do not specify a type-clause or a subtype-clause, BASIC uses the current environ- 
ment default data types. 

4. If you do not specify a scale factor, BASIC uses the current environment default scale 
factor. 
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vax> 5. In VAX-1 I BASIC, ACTIVE specifies the conditions that are to be in effect for a particular 

program module. INACTIVE specifies the conditions that are not to be in effect for a 
particular program module. If a condition does not appear in an active-clause, VAX-1 1 
BASIC uses the current environment default for the condition. See Table 16 in this 
manual for information on the INTEGER-OVERFLOW, DECIMAL-OVERFLOW, SETUP, 
DECIMAL_ROUNDING, and SUBSCRIPT_CHECKING compilation qualifiers. These 
qualifiers correspond to active-clause conditions (INTEGER OVERFLOW, DECIMAL 
OVERFLOW, SETUP, DECIMAL ROUNDING, and SUBSCRIPT CHECKING). 

Examples 

10 FUNCTION REAL DOUBLE MONTHLY-PAYMENT* & 

(DOUBLE INTEREST-RATE. & 

LONG NO-OF-PAYMENTS, & 

DOUBLE PRINCIPLE) 

20 OPTION TYPE = REAL* & 

SIZE = (REAL DOUBLE. INTEGER LONG). & 

SCALE = 4 



250 BASIC Reference Manual 



PRINT 



54.0 PRINT 

Function 

The PRINT statement transfers program data to a terminal or a terminal-format file. 

Format 



To the Controlling Terminal 

PRINT r oi itm it.lict 1 

To a Channel 

PRINT chnl-exp [, output-list ] 



output-list: [ exp ] [ sep [ exp ] ]... [ sep ] 

sep: 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). If you do not specify a chnl-exp, 
BASIC prints to the controlling terminal. 

2. Output-list specifies the expressions to be printed and the print format to be used. 

3. Exp can be any valid expression. 

4. A sep character must separate each exp. The sep characters control the print format: 

• A comma tells BASIC to skip to the next print zone before printing the expression. 

• A semicolon tells BASIC to print the expression immediately after the previous 
expression. 

General Rules 

1 . A terminal-format file must be open on the specified chnl-exp. 

2. A PRINT line has an integral number of print zones. Note, though, that the number of print 
zones in a line differs from terminal to terminal. 

3. The right margin setting, if set by the MARGIN statement, controls the width of the PRINT 
line. 

4. The PRINT statement prints string constants and variables exactly as they appear, with no 
leading or trailing spaces. 
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5. BASIC prints quoted string literals exactly as they appear. Thus, you can print quotation 
marks, commas, and other characters by enclosing them in quotation marks. 

6. A PRINT statement with no output-list prints a blank line. 

7. An exp in the output-list can be followed by more than one sep character. That is, you can 
omit an exp and specify where the next exp is to be printed by the use of multiple sep 

. characters. For example: 

100 PRINT "Name" , ."Address and "i"City" 

Run 

PROGA 16-MAR-83 IB: IB 

Name Address and City 

In this example, the double commas after "Name" cause BASIC to skip two print zones 
before printing "Address and ". The semicolon causes the next expression, "City", to be 
printed immediately after the preceding expression. 

8. When printing numeric fields, BASIC precedes each number with a space or minus sign 
and follows it with a space. If a number can be represented exactly by six decimal digits or 
less, and, optionally, a decimal point, BASIC prints it that way. 

9. BASIC rounds a number with an integer portion of six decimal digits or less (for example, 
1234.567) to six digits (1234.57). If a number has more than six decimal digits, BASIC 
rounds the number to six digits and prints it in E format. 

10. BASIC does not print trailing zeros to the right of the decimal point. If all digits to the right 
of the decimal point are zeros, BASIC omits the decimal point as well. 

11. BASIC does not print more than six digits in explicit notation. If a number requires more 
than six digits, BASIC uses E format and precedes positive exponents with a plus sign ( + ). 

12. The PRINT statement can print up to: 

• Three digits of precision for BYTE integers 

• Five digits of precision for WORD integers 

• Six digits of precision for SINGLE floating-point numbers 

• Ten digits of precision for LONG integers 

• Sixteen digits of precision for DOUBLE floating-point numbers 

• Fifteen digits of precision for GFLOAT floating-point numbers (VAX-/ J BASIC only) 

• Thirty-three digits of precision for HFLOAT floating-point numbers (VAX-1 1 BASIC only) 

• Thirty-one digits of precision for DECIMAL numbers {VAX-1 1 BASIC only) 

• The string length for STRING values 
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13. A comma or semicoion can aiso foiiow the last item in output-list: 

• When printing to a terminal, BASIC does not generate a line terminator after printing the 
last item. The next item printed with a PRINT statement is printed at the position speci- 
fied by the sep character following the last item in the first PRINT statement. 

• When printing to a terminal-format file, BASIC does not write out the record until a 
PRINT statement without trailing punctuation executes. 

14. If no punctuation follows the last item in the output-list: 

• When printing to a terminal, BASIC generates a line terminator after printing the last 
item. 

• When printing to a terminal-format file, BASIC writes out the record after printing the last 
item. 

15. If a string field does not fit on the current line: 

• When printing string elements to a terminal, BASIC prints as much as will fit on the 
current line and prints the remainder on the next line. 

• When printing string elements to a terminal-format file, BASIC prints the entire element 
on the next line. 

16. If a numeric field is the first field in a line, and the numeric field spans more than one line, 
BASIC prints part of the number on one line and the remainder on the next. Otherwise, 
numeric fields are never split across lines. If the entire field cannot be printed at the end of 
one line, the number is printed on the next line. 

17. When a number's trailing space does not fit in the last print zone, the number is printed 
without the trailing space. 

18. VAX- 7 7 BASIC rounds a floating point number with a magnitude between 0.1 and 1 .0 to 
six digits. For magnitudes smaller than 0.1, BASIC rounds the number to six digits and 
prints it in E format. 

19. For magnitudes smaller than 1, BASIC-PLUS-2 prints up to five leading zeros and six 
significant digits in explicit point unsealed notation. 

Examples 

100 PRINT "THE ANSWER IS "!SUMZ 

200 PRINT #1. EMP.NUM) EMP_NAME*! EMP.AGEZ 
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55.0 PRINT USING 

Function 

The PRINT USING statement generates output formatted according to a format string (either numeric 
or string) to a terminal or a terminal-format file. 

Format 



PRINT [ chnl-exp ] USING str-exp sep output-list 



sep: 



output-list: [ exp ] [ sep [ exp ] ]... [ sep ] 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). If you do not specify a chnl-exp, 
BASIC prints to the controlling terminal. 

2. Str-exp is the format string. It must contain at least one valid format field and must be 
followed by a sep character and at least one exp. 

3. Output-list specifies the expressions to be printed. 

• Exp can be any valid expression. 

• A sep character must separate each exp. 

4. The sep characters in the PRINT USING statement do not control the print format as in the 
PRINT statement. 

General Rules 

1 . The PRINT USING statement can print up to: 

• Three digits of precision for BYTE integers 

• Five digits of precision for WORD integers 

• Six digits of precision for SINGLE floating-point numbers 

• Ten digits of precision for LONG integers 

• Sixteen digits of precision for DOUBLE floating-point numbers 

• Fifteen digits of precision for GFLOAT floating-point numbers (VAX-? 1 BASIC only) 

• Thirty-three digits of precision for HFLOAT floating-point numbers (VAX-1 1 BASIC only) 

• Thirty-one digits of precision for DECIMAL numbers (VAX-1 1 BASIC only) 

• The string length for STRING values 
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2. A terminal-format file must be open on the specified chnl-exp or BASIC signals an error. 

3. PRINT USING rounds a floating-point number once. 

4. Format string characters control the format of numeric output. 

• The pound sign (#) reserves space for one sign or digit. 

• The comma (,) causes BASIC to insert commas before every third significant digit to the 
left of the decimal point. In the format field, the comma must be to the left of the 
decimal point, and to the right of the rightmost dollar sign, asterisk, or pound sign. A 
comma reserves space for a comma or digit. 

• The period (.) inserts a decimal point. The number of reserved places on either side of 
the period determines where the decimal point appears in the output. 

• The hyphen (-) reserves space for a sign and specifies trailing minus sign format, if 
present, it must be the last character in the format field. It makes BASIC print negative 
numbers with a minus sign after the last digit, and positive numbers with a trailing 
space. The trailing minus sign format (-) can be used as part of a dollar sign ($$) format 
field. 

• The letters CD enclosed in angle brackets (<CD>) print CR (Credit Record) after nega- 
tive numbers or zero and DR (Debit Record) after positive numbers. If present, it must 
be the last format in the format field. The (<CD>) format can be used as part of a dollar 
sign ($$) format field. 

• Four carets( ) specify E notation for floating-point numbers. They reserve four places 
for SINGLE, DOUBLE, and VAX-/ / BASIC GFLOAT values and five places for VAX-/ 7 
BASIC HFLOAT values. If present, they must be the last characters in the format field. 

• Two dollar signs ($$) reserve space for a dollar sign and a digit and cause BASIC to print 
a dollar sign immediately to the left of the most significant digit. 

• Two asterisks (**) reserve space for two digits and cause BASIC to fill the left side of the 
numeric field with leading asterisks. 

• A zero enclosed in angle brackets (<0>) prints leading zeros instead of leading spaces. 

• A percent sign enclosed in angle brackets (<%>) prints all spaces in the field if the 
value of the print item is zero. 

Note 

When the dollar sign ($$), asterisk-fill (**), or zero-fill (<0>) formats are used to form 
one print field, they are mutually exclusive. Additionally, when the zero-fill (<0>) or 
blank-if-zero (<%>) formats are used to form one print field, they also are mutually 
exclusive. 

• An underscore (_) forces the next formatting character in the format string to be inter- 
preted as a literal. It affects only the next character. If the next character is not a valid 
formatting character, the underscore has no effect and will itself be printed as a literal. 
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5. BASIC interprets any other characters in a numeric format string as string literals. 

6. Depending on usage, the same format string characters can be combined to form one or 
more print fields within a format string. For example: 

• When a dollar sign ($$) or asterisk-fill (**) format precedes a pound sign (#) , it modifies 
the pound sign format. The ($$) or (**) reserves two places, and with the pound signs 
forms one print field. For example: 

**$$### forms one field and reserves five spaces 

****## forms one field and reserves four spaces 

When these formats are not followed by a pound sign or a blank-if-zero (<%>) format, 
they reserve two places and form a separate print field. 

• When a zero-fill (<0>) or blank-if-zero (<%>) format precedes a pound sign (#), it 
modifies the pound sign format. The (<0>) or (<%>) reserves one place, and with the 
pound signs forms one print field. For example: 

**<0>#### forms one field and reserves five spaces 
**<%>### forms one field and reserves four spaces 

When these formats are not followed by a pound sign, they reserve one space and form 
a separate print field. 

• When a blank-if-zero (<%>) format follows a dollar sign ($$) or asterisk-fill (**) format, 
it modifies the ($$) or (**) format string. The (<%>) reserves one space, and with the 
($$) or (**) format string forms one print field. For example: 

**$$<%>### forms one field and reserves six spaces 
****<%>## forms one field and reserves five spaces 

When the (<%>) precedes a ($$) or (**), it reserves one space and forms a separate 
print field. 

7. In VAX—1 1 BASIC, the comma (digit separator), dollar sign (currency symbol), and deci- 
mal point (radix point) are the defaults for U.S. currency. The PRINT USING statement 
accesses the system-wide logical names for these symbols. To cause PRINT USING to 
format foreign currency, these logical names must be changed. 

8. For E notation, PRINT USING left-justifies the number in the format field and adjusts the 
exponent to compensate, except when printing zero. When printing zero in E notation, 
BASIC prints leading spaces, leading zeros, a decimal point, and zeros in the fractional 
portion if the PRINT USING string contains these formatting characters, and then the 
string "E + 00". 

9. Zero cannot be negative. That is, if a small negative number rounds to zero, it is repre- 
sented as a positive zero. 
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10. if there are reserved positions to the ieft of the decimal point, and the printed number is 
less than one, BASIC prints one zero to the left of the decimal point and pads with spaces 
to the left of the zero. 

11. If there are more reserved positions to the right of the decimal point than fractional digits, 
BASIC prints trailing zeros in those positions. 

1 2. If there are fewer reserved positions to the right of the decimal point than fractional digits, 
BASIC rounds the number to fit the reserved positions. 

13. If a number does not fit in the specified format field, BASIC prints "%", followed by the 
number in PRINT format. 

14. Format string characters control string output. All format characters except the backslash 
and exclamation point must start with a single quote ('). A single quote by itself reserves 
one character position. A single quote followed by format character(s) marks the begin- 
ning of a character format field and reserves one character position. 

Note 

VAX-11 BASIC accepts either upper- or lowercase string formatting characters. 
BASIC-PLUS-2 accepts only uppercase string formatting characters. 

• L reserves one character position. The number of Ls plus the leading single quote 
determines the field's size. BASIC left-justifies the print expression and pads with spaces 
if the print expression is less than or equal to the field's width. If the print expression is 
larger than the field, BASIC left-justifies the expression and truncates its right side to fit 
the field. 

• R reserves one character position. The number of Rs plus the leading single quote 
determines the field's size. BASIC right-justifies the print expression and pads with 
spaces if the print expression is less than or equal to the field's width. If the print 
expression is larger than the field, BASIC left-justifies the expression and truncates its 
right side to fit the field. 

• C reserves one character position. The number of Cs plus the leading single quote 
determines the field's size. If the string does not fit in the field, BASIC truncates its right 
side. Otherwise, BASIC centers the print expression in this field. If the string cannot be 
centered exactly, it is offset one character to the left. 

• E reserves one character position. The number of Es plus the leading single quote 
determines the field's size. BASIC left-justifies the print expression if it is less than or 
equal to the field's width and pads with spaces. Otherwise, BASIC expands the field to 
hold the entire print expression. 

• Two backslashes (\ \) when separated by n spaces reserve n + 2 character positions. 
PRINT USING left-justifies the string in this field. BASIC does not allow a leading 
quotation mark with this format. 

• An exclamation point (!) creates a 1 -character field. The exclamation point both starts 
and ends the field. BASIC does not allow a leading quotation mark with this format. 
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The backslash and exclamation formatting characters are included for com- 
patibility with BASIC-PLUS. DIGITAL recommends that you do not use this 
type of character field for new program development. 

15. BASIC interprets any other characters in the format string as string literals and prints them 
exactly as they appear. 

16. A comma or semicolon can also follow the last item in output-list: 

• wnen priming to a terminal, dAjiv, uucs nut. gcnciaic a nfit; * idiui dn.e. K .... .....[-, ^..~ 

last item. The next item printed with a PRINT statement is printed at the position speci- 
fied by the sep character following the last item in the first PRINT statement. 

• When printing to a terminal-format file, BASIC does not write out the record until a 
PRINT statement without trailing punctuation executes. 

1 7. If no punctuation follows the last item in the output-list: 

• When printing to a terminal, BASIC generates a line terminator after printing the last 
item. 

• When printing to a terminal-format file, BASIC writes out the record after printing the last 
item. 

Examples 

500 PRINT USING "*$«**#,#*-"» 8832. 33 » -88,3. A_UARIABLE 
300 PRINT «1 USING '"E"! "NOW IS THE TIME FOR ALL GOOD MEN" 
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56.0 PUT 

Function 



The PUT statement transfers data from the record buffer to a file. PUT statements are valid on RMS 
sequential, relative, indexed, and block I/O files. You cannot use PUT statements on terminal-format 
files, virtual array files, or files opened with ORGANIZATION UNDEFINED. 



Format 



PUT chnl-exp f , RECORD num-exp ] [ , COUNT int-exp ] 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. PUT with no RECORD clause writes data to an RMS sequential, relative, indexed, or block 
I/O file. 

• For sequential files, PUT adds a record at the end of the file. 

• For relative and block I/O files, PUT places the record in the empty cell pointed to by 
the Next Record Pointer. If the file is empty, the first PUT places a record in cell number 
one, the second in cell number two, and so on. 

• For indexed files, RMS stores records in order of ascending primary key value and 
updates all index keys. 

3. The RECORD clause allows you to randomly write records to a relative or block I /O file by 
specifying the record number. Int-exp must be between one and the maximum record 
number defined in the OPEN statement. 

4. Int-exp in the COUNT clause specifies the record's size. If there is no COUNT clause the 
record's size is that defined by the MAP or RECORDSIZE clause (RECORDSIZE overrides 
MAP) in the OPEN statement. 

• If you write a record to a file with variable-length records, int-exp must be between zero 
and the maximum record size specified in the OPEN statement, inclusive. 

• If you write a record to a file with fixed-length records, the COUNT clause serves no 
purpose. If used, int-exp must equal the record size specified in the OPEN statement. 

• In BASIC-PLUS-2, if int-exp equals zero, the entire record is written to the file. 

General Rules 

For sequential access, the file associated with chnl-exp must be open with ACCESS WRITE 
MODIFY, SCRATCH, or APPEND. 

To add records to an existing sequential file, open it with ACCESS APPEND. If you are not 
at the end of the file when attempting a PUT to a sequential file, BASIC signals "Not at end 
of file" (ERR = 149). 



1 
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3. For random access, the relative or block I/O file associated with chnl-exD must be ooen 
with ACCESS WRITE or MODIFY. 

4. After a PUT statement executes, there is no Current Record Pointer. The Next Record 
Pointer is set as follows: 

• For sequential files, PUT sets the Next Record Pointer to the end-of-file. 

• For relative and block I/O files, a sequential PUT sets the Next Record Pointer to the 
Next Record plus one. A random PUT leaves the Next Record Pointer unchanged. 

• For indexed files, PUT leaves the Next Record Pointer unchanged. 

5. When you specify a RECORD clause, BASIC evaluates int-exp and uses this value as the 
relative record number of the target cell. 

• If the target cell is empty or occupied by a deleted record, BASIC places the record in 
that cell. 

• If there is a record in the target cell, the PUT statement fails, and BASIC signals the error 
"Record already exists" (ERR= 1 53). 

6. If an existing record in an indexed file has a record with the same key value as the one you 
want to PUT to the file, BASIC signals the error "Duplicate key detected" (ERR = 134) if 
you did not specify DUPLICATES for the key in the OPEN statement. If you specified 
DUPLICATES, RMS stores the records in a first-in, first-out sequence. 

7. The number specified in the COUNT clause determines how many bytes are transferred 
from the buffer to a file: 

• If you have not completely filled the record buffer before executing a PUT, BASIC pads 
the record with nulls to equal the specified value. 

• If the specified COUNT value is less than the buffer size, the record is truncated to equal 
the specified value 

8. The number in the COUNT clause must not exceed the size specified in the MAP 
or RECORDSIZE clause in the OPEN statement or BASIC signals "Size of record invalid" 
(ERR = 156). 

9. Although block I/O files are implemented through RMS on VAX /VMS systems and 
RSX-11M/M-PLUS systems, when you write a record to a block I/O file, RMS does not 
perform the same error checking as with relative files. A PUT will write a record to a disk 
block specified in the RECORD clause, regardless of whether the block already contains a 
record. See Chapter 9 in the BASIC User's Guide for more information on RMS block I/O 
files. See the RSTS/E Programming Manual for information on RSTS/E native-mode block 
I/O files. 

Examples 

Sequential, Relative, Indexed, and Block I/O Files 

700 PUT *3 , COUNT 352, 

Relative and Block I/O Files Only 

2000 PUT #5t RECORD 133 > COUNT 1BZ 
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57.0 RANDOMIZE 

Function 

The RANDOMIZE statement gives the random number function, RND, a new starting point. 

Format 



RANDOMIZE 
RANDOM 



Syntax Rules 

None. 

General Rules 



1. Without the RANDOMIZE statement, successive runs of the same program generate the 
same random number sequence. If you use the RANDOMIZE statement before invoking 
the RND function, the starting point changes for each run. Thus, a different random num- 
ber sequence appears each time. 



Examples 

45 RANDOMIZE 
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58,0 READ 

Function 

The READ statement assigns values from a DATA statement to variables. 

Format 



READ vbl,... 



Syntax Rules 



1 . In VAX-1 1 BASIC, vbl cannot be a DEF function name, unless the READ statement is inside 
the multi-line DEF body. 

2. In BASIC-PLUS-2, vbl can be a DEF function name. If you assign a value to the DEF 
function name in this way, the next invocation of the function returns that value if it is not 
modified by the function body. 

3. If your program has a READ statement without DATA statements, BASIC signals a compile- 
time error. 



General Rules 



1 . When BASIC initializes a program unit, it forms a data sequence of all values in all DATA 
statements. An internal pointer points to the first value in the sequence. 

2. When BASIC executes a READ statement, it sequentially assigns values from the data 
sequence to variables in the READ statement variable list. As BASIC assigns each value, it 
advances the internal pointer to the next value. 

^. wA^iV. Signal? uii_ \-iiui vul \ji vjcua v 1 -^"^ — -" / " uifcric aic icvvci utiia elements mail 

READ statements. Extra data elements are ignored. 

4. The data type of the value must agree with the data type of the variable to which it is 
assigned or BASIC signals "Data format error" (ERR = 50). 

5. IF you READ a string variable, and the DATA element is an unquoted string, BASIC ignores 
leading and trailing spaces. If the DATA element contains commas, they must be inside 
quotation marks. 

6. BASIC evaluates subscript expressions in the variable list after it assigns a value to the 
preceding variable, and before it assigns a value to the subscripted variable. For example: 

100 READ A» A*(A) 



500 DATA 10, NELSON 

BASIC assigns the value 10 to variable A, then assigns the string "NELSON" to array 
element A$(10). 
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Examples 

1000 READ A» B% > C$ 



2000 DATA 32. 5, 8. ENDDATA 
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Function 

The RECORD statement lets you name and define data structures in a BASIC program and provides 
the BASIC interface to the VAX-1 1 Common Data Dictionary (CDD). You can use the defined 
RECORD name anywhere a BASIC data-type keyword is valid. 



Format 



RECORD rec-nam 




rec-component 




END RECORD [ rec-nam 


] 




data-type rec-item [ , [ data-type ] rec-item ] j 


rec-component: 


group-clause } 




variant-clause ) 


rec-item: 


unsubs-vbi [ = int-const ] ] 




array ( int-const,... ) [ = int-const ] \ 




FILL [ ( int-const ) ] [ = int-const ] ) 


group-clause: 


GROUP group-nam [ ( int-const,... ) ] 




rec-component 




END GROUP [ group-nam ] 


variant-clause: 


VARIANT 




case-clause 




END VARIANT 


case-clause: 


CASE 




[ rec-component ] 
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Syntax Rules 

1. Each line of text in a RECORD, GROUP, or VARIANT block can have an optional line 
number. 

2. Data-type can be a BASIC data-type keyword or a previously defined rec-nam or 
group-nam. Table 2 iists and describes BASIC data-type keywords. 

3. If the data-type of a rec-item is STRING, the string is fixed-length. You can supply an 
optional string length with the =int-exp clause. If you do not specify a string length, the 
default is 16. 

4. Int-const in the group-clause specifies the number of times the GROUP block occurs in the 
RECORD data structure. 

General Rules 

1 . Rec-item must conform to the rules for naming BASIC variables. 

2. Variables and arrays in a record definition are also called elementary record components. 

3. The RECORD statement names and defines a data structure called a record template, but 
does not allocate any storage. When you use the record template as a data type in a 
statement such as DECLARE, MAP, or COMMON, you declare a record instance. This 
declaration of the record instance allocates storage for the RECORD. For example: 

1000 DECLARE EMPLOYEE EMP_REC 

This statement declares a variable named EMP_REC. EMP_REC is of the user-defined 
data type EMPLOYEE. 

4. Whenever you access an elementary record component, that is, a variable named in a 
RECORD definition, you do it in the context of the record instance. Therefore, rec-item 
names need not be unique in your program. For example, you can have a variable called 
FIRST-NAME in any number of different RECORD definitions. However, you cannot use a 
BASIC keyword as a rec-item name and you cannot have two variables or arrays with the 
same name at the same level in the RECORD or GROUP definition. 
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called a RECORD block. 

6. The declarations between the CROUP keyword and the END GROUP keywords are called 
a GROUP block. The GROUP keyword is valid only within a RECORD block. 

7. A repeated GROUP is similar to an array within the record as it is zero-based. Thus, a 
repeat-count of 10 actually specifies 1 1 repetitions of the named GROUP. 

8. The declarations between the VARIANT keyword and the END VARIANT keywords are 
called a VARIANT block. 

9. The amount of space allocated for a VARIANT field in a RECORD is equal to the space 
needed for the variant field requiring the most storage. A record component outside of this 
overlaid field determines which record variant is used. 

10. The rec-nam qualifies the group-nam and the group-nam qualifies the rec-item. You can 
access a particular rec-item within a record by specifying rec-nam ::group-nam::rec-item. 
This specification is called a fully qualified reference. The full qualification of a rec-item is 
also called a component path name. 

11. The group-nam is optional in a rec-item specification unless there is more than one 
rec-item with the same name. For example: 

10 DECLARE EMPLOYEE EMP_REC 



100 RECORD Address 

STRING Street* City* State* Zip 
END RECORD Address 
200 RECORD Employee 

GROUP Emp_name 

STRING Fi rst = 15 
STRING Middle = 1 
STRING Last = 15 
END GROUP Emp-name 
ADDRESS Work 
ADDRESS Home 
END RECORD Employee 

You can access the rec-item "Last" by specifying only "EMP_REC::Last" because only one 
rec-item is named "Last." However, if you try to reference "EMP_REC::City", BASIC signals 
an error because "City" is an ambiguous field, a component of both "Work" and "Home." 
To access "City," you must specify either "EMP_REC::Work::City" or 
"EMP_REC::Home::City." 
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Examples 

1000 



RECORD 


EMP_WAGE_CLASS 








GROUP 


EMP_NAME 










STRING 


Last = 


15 






STRING 


Fi rst = 


= 14 






STRING 


Middle 


= 1 




END GROUP EMP_NAME 






GROUP 


EMP_ADDRESS 








STRING 


St reel 


= 15 






STRING 


City = 


20 



STRING State = 2 
DECIMAL(SfO) Zip 
END GROUP EMP.ADDRESS 
STRING WAGE-CLASS = 2 
VARIANT 

CASE 

GROUP HOURLY 

DECIMALS. 2) Hourly_waSe 
SINGLE ReSular_pay_y td 
SINGLE Ove rt ime_pay_y t d 
END GROUP HOURLY 
CASE 

GROUP SALARIED 

DECIMAL(7.2) Ye a rl y _s al a ry 
SINGLE Pay_ytd 
END GROUP SALARIED 
CASE 

GROUP EXECUTIVE 

DECIMAL(B,2> Yea rl y_s al a ry 
SINGLE Pay_ytd 
SINGLE Expenses.ytd 
END GROUP EXECUTIVE 
END VARIANT 
END RECORD EMP_WAGE_CLASS 
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60.0 REM 

Function 

The REM statement permits program documentation. 

Format 



REM [comment] 



Syntax Rules 

1 . REM must be the only statement on the line or the last statement on a multi-statement line. 

2. Because the REM statement is not executable, you can place it anywhere in a program, 
except where other statements, such as SUB and END SUB, must be the first or last 
statement in a program unit. 

3. BASIC interprets every character between the keyword REM and the next line number as 
part of the comment. 

General Rules 

1 . When the REM statement is the first statement on a line-numbered line, BASIC treats any 
reference to that line number as a reference to the next higher-numbered executable 
statement. 

2. The REM statement is similar to the comment field that begins with an exclamation point, 
with one exception: the REM statement must be the last statement on a multi-statement 
line. The exclamation point comment field can be ended with a line terminator and fol- 
lowed by a BASIC statement. See Section I of this manual for more information on the 
comment field. 

Examples 

500 REM THIS IS A COMMENT 
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61.0 REMAP 

Function 

The REMAP statement defines or redefines the position in the record buffer of variables named in the 
MAP DYNAMIC statement. 

Format 



REMAP (map-nam) remap-item,... 


remap-item: 


num-vbl-nam 

num-array-nam ( [ int-exp,... ] ) 

str-vbl-nam [ = int-exp ] 


"< 




< 


str-array-nam ( [ int-exp,... ] ) [ = 


int-exp ] ► 




[ data-type ] FILL [ ( int-exp ) ] [ 


= int-exp ] 






FILL% [ ( int-exp ) ] 








FILLS [ ( int-exp ) ] [ = int-exp ] 


j 





Syntax Rules 

1 . Map-nam is the name of a map area declared in the MAP and MAP DYNAMIC statements. 

2. Remap-item names a variable, array, or array element declared in a preceding MAP 
DYNAMIC statement: 

• Num-vbl-nam specifies a numeric variable or array element. Num-arr-nam () specifies an 
entire numeric array. 

• Str-vbl-nam specifies a string variable or array element. Str-arr-nam () specifies an entire 
fixed-length string array. You can specify the number of bytes to be reserved for string 
variables and array elements with the = int-exp clause. The default string length is 16. 

3. Remap-item can also be a FILL item. The FILL, FILL%, and FILL$ keywords let you reserve 
parts of the record buffer. Int-exp specifies the number of FILL items to be reserved. The 
= int-exp clause allows you to specify the number of bytes to be reserved for string FILL 
items. Table 21 describes FILL item format and storage allocation. 

Note 

In the applicable formats of FILL, (int-const) represents a repeat count, not an 
array subscript. FILL (n), for example, represents n elements, not n + 1 . 

4. All remap-items, except FILL items, must have been named in a previous MAP DYNAMIC 
statement, or BASIC signals an error. 
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5. Data-type can be any BASIC data-type keyword or, in VAX—1 1 BASIC, a data type defined 
in a RECORD statement. Data-type keywords, size, range, and precision are listed in Table 
2 in this manual. You can specify a data type only for FILL items. 

• When you specify a data-type, all following FILL items are of that data type until you 
specify a new data type. 

• If you do not specify any data-type, FILL items take the current default data type and size. 

• FILL items following a data-type cannot end in a dollar sign or percent sign suffix 
character. 

6. Remap-items must be separated with commas. 

General Rules 

1 . The REMAP statement does not affect the amount of storage allocated to the map area. 

2. Each time a REMAP statement executes, BASIC sets record pointers to the named map area 
for the specified variables from left to right. 

3. The REMAP statement must be preceded by a MAP DYNAMIC statements or BASIC signals 
the error "No such MAP area <name>". The MAP statement creates a named area of 
static storage, the MAP DYNAMIC statement specifies the variables whose positions can 
change at run time, and the REMAP statement specifies the new positions for the variables 
names in the MAP DYNAMIC statement. 

4. Until the REMAP statement executes, all variables named in the MAP DYNAMIC statement 
point to the first byte of the MAP area and all string variables have a length of zero. When 
the REMAP statement executes, BASIC sets the internal pointers as specified in the REMAP 
statement. For example: 

100 MAP (DUMMY) STRING MAP.BUFFER = 50 

MAP DYNAMIC (DUMMY) LONG At STRING Bt SINGLE C(7) 
REMAP (DUMMY) B=14 t At CO 

The REMAP statement sets a pointer to byte 1 of DUMMY_MAP for string variable B, a 
pointer to byte 15 for LONG variable A, and pointers to bytes 19, 23, 27, 31, 35, 39, 43, 
and 47 for the elements in SINGLE array C. 

5. You can use the REMAP statement to redefine the pointer for an array element or variable 
more than once in a single REMAP statement. For example: 

100 MAP (DUMMY) STRING = 48 

MAP DYNAMIC (DUMMY) LONG At B<10> 
REMAP (DUMMY) B( ) t B(0) 

This REMAP statement sets a pointer to byte 1 in DUMMY_MAP for array B. Since array B 
uses a total of 44 bytes, the pointer for the first element of array B, B(0) points to byte 45. 
References to array element B(0) will be to bytes 45 through 48. Pointers for array elements 
1 through 10 are set to bytes 1, 4, 8, 12, and so forth. 

6. Because the REMAP statement is local to a program module, it affects pointers only in the 
program module in which it executes. 
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Examples 

100 MAP (EMPREC) STRING MAP.BUFFER = 100 

HAP DYNAMIC (EMPREC) STRING EMP.NAME, 8, 

LONG BADGE.NO , & 

STRING STREET. CITY, STATE, & 

WORD ZIP, & 

STRING START-DATE 

REMAP (EMPREC) EMP.NAME =20, & 

BADGE.NO, &. 

STREET =10, & 

CITY = 10, 8, 

STATE = 2, g. 

ZIP, 8= 

START.DATE = 8 



500 REMAP (EMPREC) EMP.NAME =10, 8= 

BADGE.NO, 8, 

STRING FILL = 32, 8. 

WORD FILL, 8. 
START.DATE = 8 
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Function 

The RESTORE statement resets the DATA pointer to the beginning of the DATA sequence or sets the 
record pointer to the first record in a file. RESET is a synonym for RESTORE. 

Format 




Syntax Rules 



1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Int-exp must be between zero and the number of keys in the file minus one, inclusive. 

General Rules 

1. The RESTORE statement is not allowed on virtual array files or on files opened on unit 
record devices. 

2. If you do not specify a chnl-exp, RESTORE resets the DATA pointer to the beginning of the 
DATA sequence. 

3. RESTORE affects only the current program unit. Thus, executing a RESTORE statement in a 
subprogram does not affect the DATA pointer in the main program. 

4. If there is no chnl-exp, and the program has no DATA statements, RESTORE has no effect. 

5. The file specified by chnl-exp must be open. 

6. If chnl-exp specifies a magnetic tape file, BASIC rewinds the tape to the first record in the 
file. 

7. The KEY clause applies to indexed files only. It sets a new key of reference equal to int-exp 
and sets the Next Record Pointer to the first logical record in that key. 

8. For indexed files, the RESTORE statement without a KEY clause sets the Next Record 
Pointer to the first logical record specified by the current key of reference. If there is no 
current key of reference, the RESTORE statement sets the Next Record Pointer to the first 
logical record of the primary key. 

9. If you use the RESTORE statement on any file type other than indexed, BASIC sets the Next 
Record Pointer to the first record in the file. 

Examples 

400 RESTORE *71 > KEY «4% 
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Function 

The RESUME statement marks an exit point from an error-handling routine. BASIC clears the error 
condition and returns program control to a specified line number or to the program block in which 
the error occurred. 

Format 



RESUME [ lin-num 



Syntax Rules 

1. Lin-num must exist within the same program unit as the RESUME statement. 

2. The RESUME statement cannot be used in a multi-line DEF unless the lin-num is also in 
the DEF function definition. 

General Rules 

1 . The RESUME statement does not accept a label as an argument. Therefore, you should 
number lines that are to receive control from the error handler. 

2. When no lin-num is specified in a RESUME statement, BASIC transfers control based on 
where the error occurs. If the error occurs on a numbered line containing a single state- 
ment, BASIC always transfers control to that statement. However, if the error occurs 
within a multi-statement line: 

• Within a FOR, WHILE, or UNTIL loop, BASIC transfers control to the first statement that 
follows the FOR, WHILE, or UNTIL statement. 

• Within a SELECT block, BASIC transfers control to the start of the CASE block in which 
the error occurs. 

• After a loop or SELECT block, BASIC transfers control to the statement that follows the 
NEXT or END SELECT statement. 

• If none of the above conditions occurs, BASIC transfers control back to the statement 
that follows the most recent line number or label. 

3. To simplify and clarify error handling, DIGITAL recommends that the RESUME statement 
always be used with lin-num. 
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multi-statement line, regardless of which statement caused the error. 

5. A RESUME statement cannot transfer control out of the current program unit. Thus, a 
RESUME statement with no lin-num cannot terminate an error handler in the following 
situation: (1) the error handler is handling an error that occurred in a subprogram or an 
external function, and (2) the error was passed to the calling program's error handler by 
an ON ERROR GO BACK statement or by default. 

6. The execution of a RESUME with no lin-num is illegal if there is no error active. A 
RESUME with a lin-num is always legal. After clearing the error condition, BASIC transfers 
control to the specified line. 

Examples 

19100 RESUME 300 
19990 RESUME 
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64.0 RETURN 

Function 

The RETURN statement transfers control to the statement immediately following the most recently 
executed GOSUB or ON GOSUB statement in the current program unit. 

Format 



RETURN 



Syntax Rules 



1 . RETURN is the last statement executed in a subroutine even if it is not the last statement in 
the subroutine. 

General Rules 

1 . Execution of a RETURN statement before the execution of a GOSUB or ON GOSUB causes 
BASIC to signal "RETURN without GOSUB" (ERR = 72). 

Examples 

800 RETURN 
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65.0 RSET 



Function 



The RSET statement assigns right-justified data to a string variable. RSET does not change a string 
variable's length. 

Format 



RSET str-vbl,... = str-exp 



Syntax Rules 

1 . BASIC evaluates the str-vbl subscript expression (if present) before assigning values. 

2. Str-vbl cannot be a DEF function name, unless the RSET statement is inside the DEF 
function definition. 

General Rules 

1 . The RSET statement treats strings as fixed-length. It does not change the length of str-vbl nor 
does it create new storage locations. 

2. If str-vbl is longer than str-exp, RSET right-justifies the data and pads it with spaces on the 
left. 

3. If str-vbl is shorter than str-exp, RSET truncates str-exp on the left. 
Examples 

100 RSET ZZ$ = "LMNOP" 
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Function 



The SCRATCH statement deletes the Current Record and all following records in an RMS sequential 
file. 

Format 



SCRATCH chnl-exp 



Syntax Rules 

None. 

General Rules 

1. Before you execute the SCRATCH statement, the file must be opened with ACCESS 
SCRATCH. 

2. The SCRATCH statement applies to ORGANIZATION SEQUENTIAL files only. 

3. The SCRATCH statement has no effect on terminals or unit record devices. 

4. For disk files, the SCRATCH statement discards the current record and all that follow it in 
the file. The file is not physically shortened. 

5. For magnetic tape files, the SCRATCH statement overwrites the current record with two 
end-of-file marks. 

Examples 

BOO SCRATCH *Q1 
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67.0 SELECT 

Function 

The SELECT statement lets you specify an expression, a number of possible values the expression may 
have, and a number of alternative statement blocks to be executed for each possible case. The END 
SELECT keywords terminate the SELECT block. The code between SELECT and END SELECT is called 
a SELECT block, and the code between CASE statements is called a CASE block. 

Format 



SELECT expl 






case-clause 






[ else-clause ] 






END SELECT 






case-clause: 


CASE case-item,... 

[ statement ] ... 




case-item: 


[ rel-op ] exp2 ) 
exp3 TO exp4 | 




else-clause: 


CASE ELSE 






[ statement ] ... 





Syntax Rules 



1 . £xp7 is the expression to be tested against the case-clauses and the else-clause. It can be 
numeric or string. 

• Case-clause consists of the CASE keyword followed by a case-item and statements to be 
executed when the case-/tem is true. 

• Else-clause consists of the CASE ELSE keywords followed by statements to be executed 
when no previous case-item has been selected as true. 

2. Case-item is either an expression to be compared with exp7 or a range of values separated 
with the keyword TO. 

• Rel-op is a relational operator specifying how exp7 is to be compared to exp2. If you do 
not include a rel-op, BASIC assumes the equals ( = ) operator. BASIC executes the state- 
ments in the CASE block when the specified relational expression is true. 
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Separate multiple ranges with commas. BASIC executes the statements in the CASE block 
when exp 7 falls within any of the specified ranges. 

3. A SELECT statement can have only one else-clause. The else-clause is optional and, when 
present, must be the last CASE block in the SELECT block. 

General Rules 

1 . Each statement in a SELECT block can have its own line number. 
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it. BASIC signals an error if you do not include the END SELECT keywords. 

3. Each CASE keyword establishes a CASE block. The next CASE or END SELECT keyword 
ends the CASE block. 

4. You can nest SELECT blocks within a CASE or CASE ELSE block. 

5. BASIC evaluates exp 7 when the SELECT statement is first encountered; BASIC then com- 
pares exp 7 with each case-clause in order of occurrence until a match is found or until a 
CASE ELSE block or END SELECT is encountered. 

6. The following conditions constitute a match: 

• £xp7 satisfies the relationship to exp2 specified by rel-op. 

• Exp 7 is greater than or equal to exp3, but less than or equal to exp4, greater than or equal 
to exp5 but less than or equal to exp6, and so on. 

7. When a match is found between exp 7 and a case-item, BASIC executes the statements in 
the CASE block where the match occurred. If ranges overlap, the first match causes BASIC 
to execute the statements in the CASE block. After executing CASE block statements, 
control passes to the statement immediately following the END SELECT keywords. 

8. If no CASE match occurs, BASIC executes the statements in the else-clause, if present, and 
then passes control to the statement immediately following the END SELECT keywords. 

9. If no CASE match occurs and you do not supply a case-else clause, control passes to the 
statement following the END SELECT keywords. 

Examples 

100 SELECT A% + B% + CI 
CASE = 100 

PRINT 'THE VALUE IS EXACTLY 100' 
CASE 1 TO SS 

PRINT 'THE VALUE IS BETWEEN 1 AND 9S ' 
CASE > 100 

PRINT 'THE VALUE IS GREATER THAN 100' 
CASE ELSE 

PRINT 'THE VALUE IS LESS THAN 100' 
END SELECT 
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68.0 SLEEP 



Function 



The SLEEP statement suspends program execution for a specified number of seconds or until a 
carriage return is entered from the controlling terminal. 

Format 



SLEEP int-exp 



Syntax Rules 

1. In VAX-11 BASIC, int-exp must be between and 2147483647, inclusive; if it is greater 
than 2147483647, BASIC signals the error "Integer error or overflow" (ERR = 51). 

2. In BASIC-PLUS-2, int-exp must be between and 32767, inclusive; if it is greater than 
32767, BASIC signals "Integer error" and does not suspend program execution. 

General Rules 

1 . Int-exp is the number of seconds BASIC waits before resuming program execution. 

2. Pressing the RETURN key on the controlling terminal cancels the effect of the SLEEP 
statement. 

Examples 

SO SLEEP 120X 
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69,0 STOP 

Function 

The STOP statement halts program execution. 

Format 



STOP 



Syntax Rules 

None. 

General Rules 

1 . STOP is valid anywhere in a program. 

2. The STOP statement does not close files. 
VAX- 7 I BASIC 

1 . When a STOP statement executes in a program executed with the RUN command in the 
BASIC environment, BASIC prints the line number and module name associated with the 
STOP statement, then displays the BASIC prompt. In response to the prompt, you can type 
immediate mode statements, CONTINUE to resume program execution, or any valid com- 
piler command. See BASIC on VAX/VMS Systems for more information on immediate 
mode. 

2. When a STOP statement is in an executable image, the line number, module name, and a 
pound sign (#) prompt are printed. In response to the prompt, you can type CONTINUE to 
continue program execution or EXIT to end the program. If the program module was 
compiled with the /NOLINE qualifier, no line number is displayed. 

BASIC-PLUS-2 

1 . When a STOP statement executes in a program executed with the RUN /DEBUG command 
or compiled with the /DEBUG qualifier, control passes to the BASIC-PLUS-2 debugger. 
The debugger prints the line number and module name associated with the STOP state- 
ment, then displays the pound sign (#) prompt. You can then use BASIC-PLUS-2 debugger 
commands to analyze and debug your program. See Part VI in this manual for information 
on BASIC-PLUS-2 debugger commands. Use the EXIT command to exit from the debugger 
and end the program. 

2. When a STOP statement executes in a program executed with RUN or compiled without 
the /DEBUG qualifier, the line number of the STOP statement and a pound sign (#) 
prompt are printed. In response to the prompt, you can type CONTINUE to continue 
program execution or EXIT to end the program. The EXIT command closes all files before 
leaving the program. 

Examples 

95 STOP 
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70.0 SUB 

Function 

The SUB statement marks the beginning of a BASIC subprogram and specifies its parameters by 
number and data type. 

Format 

VAX-11 BASIC 




VAX) 



SUB sub-name [ pass-mech ] [ ( [ formal-param ],... ) ] 






[ statement ]... 








END SUB 










SUBEND 








pass-mech: 


BYDESC j 
BY REF j 






formal-param: I unsubs-vbl-nam 


) 




[ data-type ]J array-nam ( 


int-const 


■ •■• ) I [ = 


int-const ] [ pass-mech ] 


I 


U J 


) 





BAS1C-PLUS-2 



SUB sub-name [ ( [ formal-param 

[ statement ]... 

END SUB ' 
SUBEND 



formal-param: I unsubs-vbl-nam 

[ data-type ] J array-nam ( f int-const | ,... ) 



fint-constl ,... 
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Syntax niiicS 



1 . Sub-nam is the name of the separately compiled subprogram. 

2. Formal-param specifies the number and type of parameters for the arguments the SUB 
subprogram expects to receive when invoked. 

• Empty parentheses indicate that the SUB subprogram has no parameters. 

• Data-type specifies the data type of a parameter. If you do not specify a data type, 
parameters are of the default data type and size. When you do specify a data type, all 
following n arameters are of that data type until you specify a new data type. Data-type 
keywords, size, range, and precision are listed in Table 2 in this manual. 

• If you specify a datatype, unsubs-vbl-nam and array-nam cannot end in a percent sign 
(%) or dollar sign ($). 

3. The SUB statement must be the first statement in the SUB subprogram. 

4. Compiler directives and comment fields (!), because they are not BASIC statements, may 
precede the SUB statement. However, they cannot precede the subprogram's first 
numbered line. Note that REM is a BASIC statement; therefore, it cannot precede the SUB 
statement. 

5. Every SUB statement must have a corresponding END SUB statement or SUBEND 
statement. 

6. Any BASIC statement except END, FUNCTION, END FUNCTION, or EXIT FUNCTION 
can appear in a SUB subprogram. 

VAX-1 1 BASIC 

1 . Sub-nam can consist of from 1 to 31 characters and must conform to the following rules: 

• The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), periods (.), or underscores (_). 

• A quoted name can consist of any combination of printable ASCII characters. 

2. Data-type can be any BASIC data-type keyword or a data type defined in the RECORD 
statement. 

3. If the data type is STRING, the =int-const clause allows you to specify the length of the 
string. If you do not specify, a string length, the default length is 16. 

4. Pass-mech specifies the parameter passing mechanism by which the subprogram receives 
arguments when called by non-BASIC programs. 

5. A pass-mech clause outside the parentheses applies by default to all SUB parameters. A 
pass-mech clause in the formal-param list overrides the specified default and applies only 
to the immediately preceding parameter. 

6. If you do not specify a pass-mech, the SUB program receives arguments by the default 
passing mechanisms, as shown in Table 19. 



February 1984 BASIC Reference Manual 281 



SUB 



7. Parameters defined in formal-param must agree in number, type, ordinality, and 
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8. You can specify from 1 to 32 formal-params. 
BP2) BASIC-PLUS-2 

1 . Sub-nam can consist of from one to six characters and must conform to the following rules: 

• The first character of an unquoted name must be an alphabetic character (A through Z). 
The remaining characters, if present, can be any combination of letters, digits (0 through 
9), dollar signs ($), or periods (.). 

• A quoted name can consist of any combination of alphabetic characters, digits, dollar 
signs ($), periods (.), or spaces. 

2. Data-type can be any BASIC data-type keyword. 

3. Parameters defined in formal-param must agree in number, type, and ordinality with the 
arguments specified in the CALL statement of the calling program. 

4. You can specify from one to eight formal-params. 
General Rules 

1 . All variables, except those named in MAP and COMMON statements and in DATA state- 
ments in a subprogram, are local to that subprogram. 

2. BASIC initializes local variables upon each entry to the subprogram as follows: 

• Numeric variables are initialized to zero. 

• String variables are initialized to the null string. 
vax> VAX- 7 1 BASIC 

1. SUB subprograms receive parameters BY REF or BY DESC. A SUB subprogram cannot 
receive any parameter BY VALUE. Table 19 lists and describes VAX-1 1 BASIC parameter 
passing mechanisms. 

• BY REF specifies that the subprogram receives the argument's address. 

• BY DESC specifies that the subprogram receives the address of a VAX-/ 7 BASIC descrip- 
tor. For information about the format of a VAX-7 7 BASIC descriptor for strings and 
arrays, see Appendix C in BASIC on VAX/VMS Systems. For information on other types 
of descriptors, see the VAX Architecture Handbook. 

2. By default, VAX-7 7 BASIC subprograms receive numeric unsubs-vbls BY REF and all other 
parameters BY DESC. You can override these defaults for strings and arrays with a BY 
clause: 

• If you specify a string length with the = int-const clause, you must also specify BY REF If 
you specify BY REF and do not specify a string length, BASIC uses the default string 
length of 16. & 

• If you specify array bounds, you must also specify BY REF. 

3. RECORD data structures are initialized to zero or the null string. 

4. VAX-7 / 6AS/C subprograms may be called recursively. 
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BASIC-PLUS-2 /^\ 

1. You cannot specify how subprograms receive parameters in BASIC-PLUS-2. Numeric 
unsubs-vbls are received BY REF and string unsubs-vbls and entire arrays are received BY 
DESC. Table 20 lists and describes BASIC-PLUS-2 BASIC parameter passing mechanisms. 

• BY REF specifies that the subprogram receives the argument's address. 

• BY DESC specifies that the subprogram receives the address of a BASIC-PLUS-2 descrip- 
tor. For information about the format of a BASIC-PLUS-2 descriptor, see Appendix C in 
BASIC on RSX-1 1M/M-PLUS Systems and BASIC on RSTS/E Systems. 

2. BASIC-PLUS-2 subprograms cannot be called recursively. 

Examples 

VAX-/ 1 BASIC 

100 SUB SUB3 BY REF (DOUBLE A» B. & 

STRING EMP_NAM = 20 BY DESC* i 

WAGE(20)> 



900 END SUB 

BASIC-PLUS-2 

100 SUB SUBPR0 (BYTE AGE* DOUBLE WAGE(20>20)» STRING EMP_NAME) 
900 END SUB 
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71.0 SUBEND 

Function 

The SUBEND statement is a synonym for END SUB. See the END statement for syntax rules. 

Format 



SUBEND 
END SUB 
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72.0 SUBEXIT 

Function 

The SUBEXIT statement is a synonym for the EXIT SUB statement. See the EXIT statement for syntax 
rules. 

Format 



SUBEXIT 
EXIT SUB 
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73.0 UNLESS 

Function 

UNLESS modifies a statement. BASIC executes the modified statement only if a conditional expres- 
sion is false. 

Format 



statement UNLESS cond-exp 



Syntax Rules 

1 . The UNLESS qualifier cannot be used on nonexecutable statements or on statements such 
as SELECT, IF, and DEF that establish a statement block. 

2. Cond-exp can be any conditional expression. 
General Rules 

1 . BASIC executes the statement only if cond-exp is false (value zero). 
Examples 

100 PRINT "A DOES NOT EQUAL 3" UNLESS AX = 32 
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74.0 UNLOCK 

Function 

The UNLOCK statement unlocks the current record or bucket locked by the last FIND or GET 
statement. 

Format 



UNLOCK chnl-exp 



Syntax Rules 

1 . Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

General Rules 

1 . A file must be opened on chnl-exp before UNLOCK can execute. 

2. The UNLOCK statement does not apply to files not on disk. 

3. If the current record is not locked by a previous GET or FIND statement, the UNLOCK 
statement has no effect and BASIC does not signal an error. 

4. The UNLOCK statement does not affect record buffers. 

5. After you execute the UNLOCK statement, you cannot UPDATE or DELETE the current 
record. 

Examples 

90 UNLOCK #10 
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75.0 UNTIL 

Function 

The UNTIL statement marks the beginning of an UNTIL loop or modifies the execution of another 
statement. 

Format 



Conditional 

UNTIL cond-exp 

[ statement ]... 
NEXT 

Statement Modifier 

statement UNTIL cond-exp 



Syntax Rules 

1 . Cond-exp can be any valid relational or logical expression. 
Conditional 
1 . A NEXT statement must end the UNTIL loop. 

General Rules 

Conditional 

1 . BASIC evaluates cond-exp before each loop iteration. If the expression is false (value zero), 
BASIC executes the loop. If the expression is true (value nonzero), control passes to the first 
executable statement after the NEXT statement. 

Statement Modifier 

1 . BASIC executes the statement repeatedly until cond-exp is true. 

Examples 

Conditional 

10 UNTIL A >= 5 

A = A + ,01 
TOTAL = TOTAL + 1 
NEXT 

Statement Modifier 

100 A = A + 1 UNTIL A >= 200 
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76.0 UPDATE 



Function 



The UPDATE statement replaces a record in a file with a record in the record buffer. UPDATE is valid 
only on RMS sequential, relative, and indexed files. 

Format 



UPDATE chnl-exp [ , COUNT int-exp 



Syntax Rules 

1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It 
must be immediately preceded by a pound sign (#). 

2. Int-exp in the COUNT clause specifies the record's size. 

3. In BASIC-PLUS-2 , if int-exp equals zero, the entire record is written to the file. 

General Rules 

1 . The file associated with chnl-exp must be a disk file opened with ACCESS MODIFY. 

2. Each UPDATE statement must be preceded by a successful GET or FIND operation or 
BASIC signals "No current record" (ERR = 131). Because FIND locates but does not 
retrieve records, you must specify a COUNT clause in the UPDATE statement when the 
preceding operation was a FIND. Int-exp in the COUNT clause must exactly specify the 
size of the oid record. 

3. After an UPDATE statement executes, there is no Current Record Pointer. The Next Record 
Pointer is unchanged. 

4. The length of the new record must be the same as that of the existing record for all files 
with fixed-length records. If the new record is larger than the existing record, BASIC 
truncates the right side of the new record to fit the existing record. If the new record is 
smaller than the existing record, the file gets corrupted. 

5. If you write a record to a sequential file with fixed-length records, int-exp in the COUNT 
clause must exactly match the size of the old record. 

6. For sequential files with variable-length records, the length of the new record must be the 
same as that of the existing record. 

• If you specify a COUNT clause, int-exp must match the size of the existing record. 

• In the absence of a COUNT clause, UPDATE uses the record size set by the last success- 
ful GET on that channel. 
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7. For relative files with variable-length records, the new record can be larger or smaller than 
the record it replaces. 

• The new record must be smaller than or equal to the maximum record size set with the 
MAP or RECORDSIZE clause when the file was opened. 

• You must use the COUNT clause to specify the size of the new record if it is different 
from that of the record last accessed by a GET on that channel. 

8. For indexed files with variable-length records, the new record can be larger or smaller than 
the record it replaces. 

• When an indexed file permits duplicate primary keys, an updated record must be the 
same length as the old one. 

• When the program does not permit duplicate primary keys, the new record can be no 
longer than the maximum record size specified in the MAP or RECORDSIZE clause when 
the file was opened and must include at least the primary key field. 

• An alternate key for the new record can differ from that of the existing record only if the 
OPEN statement for that file specified CHANGES for the alternate key. 

9. On RSTS/E systems, you can use UPDATE on native-mode files opened with mode 1 bit set 
(UPDATE mode). 

Examples 

100 UPDATE »4. COUNT 32 
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77,0 WAIT 

Function 

The WAIT statement specifies the number of seconds the program waits for terminal input before 
signaling an error. 

Format 



WAIT int-exp 



Syntax Rules 

1 



The WAIT statement must precede an INPUT, INPUT LINE, LINPUT, MAT INPUT, or MAT 
LIN PUT statement, or it has no effect. 

2. In VAX-11 BASIC, int-exp must be between and 2147483647, inclusive; if it is greater 
than 2147483647, BASIC signals the error "Integer error or overflow" (ERR = 51). 

3. In BASIC-PLUS-2, int-exp must be between and 32767, inclusive; if it is greater than 
32767, BASIC signals "Integer error" and the WAIT statement has no effect. 

General Rules 

1. Int-exp is the number of seconds BASIC waits for input before signaling the error, 
"Keyboard wait exhausted" (ERR = 15). 

2. After BASIC executes a WAIT statement, all input statements wait the specified amount of 
time before BASIC signals an error. 

3. WAIT disables the WAIT statement. 
Examples 

50 WAIT BO 

INPUT "YOU HAVE SIXTY SECONDS TO TYPE YOUR NAME"? NAME* 
WAIT 
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78.0 WHILE 

Function 

The WHILE statement marks the beginning of a WHILE loop or modifies the execution of another 
statement. 

Format 



Conditional 

WHILE cond-exp 

[ statement ]... 
NEXT 

Statement Modifier 

statement WHILE cond-exp 



Syntax Rules 

1. Cond-exp can be any valid relational or logical expression. 
Conditional 
1 . A NEXT statement must end the WHILE loop. 

General Rules 

Conditional 

1 . BASIC evaluates cond-exp before each loop iteration. If the expression is true (value non- 
zero), BASIC executes the loop. If the expression is false (value zero), control passes to the 
first executable statement after the NEXT statement. 

Statement Modifier 

1 . BASIC executes the statement repeatedly as long as cond-exp is true. 

Examples 

Conditional 

10 WHILE X < 100 

X = X + SQR(X) 
NEXT 

Statement Modifier 

100 XX = XX + IX WHILE XX < 1001 
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1.0 ABS 

Function 

The ABS function returns a floating-point number that equals the absolute value of a specified 
floating-point expression. 

Format 



real-vbl = ABS(real-exp) 



Syntax Rules 

None. 

General Rules 



1 . BASIC expects the argument of the ABS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

2. The returned floating-point value is always greater than or equal to zero. The absolute 
value of zero is zero. The absolute value of a positive number equals that number. The 
absolute value of a negative number equals that number multiplied by minus one. 

Examples 

400 A = ABS(-100 * G) 

410 B = -39,2 

420 PRINT ABS(B> , A 
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2.0 ABS% 

Function 

The ABS% function returns an integer number that equals the absolute value of a specified integer 
expression. 

Format 



int-vbl = ABS%(int-exp) 



Syntax Rules 

None. 

General Rules 



1 . If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default integer size. 

2. The returned value is always greater than or equal to zero. The absolute value of zero is 
zero. The absolute value of a positive number equals that number. The absolute value of a 
negative number equals that number multiplied by minus one. 

Examples 

400 A = ABSX(-100X * GZ) 

410 B = -39 

420 PRINT ABS%(B> > A 
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3.0 ASCII 

Function 

The ASCII function returns the ASCII value (base 10) of a string's first character. 

Format 




Syntax Rules 

None. 

General Rules 

1 . The ASCII value of a null string is zero. 

2. The ASCII function returns an integer value of the default size between and 255, 
inclusive. 

Examples 

500 ASC.VAL = ASCII (EMP_ NAM*) 



BASIC Reference Manual 295 



ATN 



4.0 ATN 

Function 

The ATN function returns the angle, in radians, of a specified tangent. 

Format 



real-vbl = ATN(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . ATN returns a value from -PI/2 through PI/2. 

2. The returned angle is expressed in radians. 

3. BASIC expects the argument of the ATN function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 

150 ANGLE_RAD = ATN(T) 

160 ANGLE.DEG = ANGLE _ RAD / ( P I / 180 ) 
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Function 

The BUFSIZ function returns the buffer size, in bytes, of a specified channel. 

Format 



int-vbl = BUFSIZ(chnl-exp) 



Syntax Rules 

None. 

General Rules 

1. Chnl-exp is the channel expression of an open file. If the specified channel is closed, 
BUFSIZ returns zero. You cannot include a pound sign (#) in chnl-exp. 

2. In BASIC-PLUS-2, BUFSIZ of channel zero returns the current terminal width or, in a 
batch stream, 512. 

3. In VAX-1 1 BASIC, BUFSIZ of channel zero always returns 132. 

4. Int-vbl is a WORD integer in BASIC-PLUS-2 and a LONG integer in VAX-1 1 BASIC. 
Examples 

100 A = BUFSIZ<2) 
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6.0 CCPOS 

Function 

The CCPOS function returns the output record's current character or cursor position on a specified 
channel. 

Format 



int-vbl = CCPOS(chnl-exp) 



Syntax Rules 

None. 

General Rules 

1 . Chnl-exp must specify an open file or terminal. You cannot include a pound sign (#) in 
chnl-exp. 

2. If chnl-exp is zero, CCPOS returns the current character position of the controlling 
terminal. 

3. The int-vbl returned by the CCPOS function is of the default integer size. 

4. The CCPOS function counts only characters. If you use cursor addressing sequences such 
as escape sequences, the value returned will not be the cursor position. 

5. The first character position on a line is zero. 
Examples 

100 CHNLO = CCPOS (0) 
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7,0 CHR$ 

Function 

The CHR$ function returns a 1-character string that corresponds to the ASCII value you specify. 

Format 



str-vbl = CHR$(int-exp) 



Syntax Rules 

None. 

General Rules 

1 . CHR$ returns the character whose ASCII value equals int-exp. If int-exp is greater than 255, 
BASIC treats it modulo 256. For example, CHR$(325) is the same as CHR$(69). 

2. BASIC treats all arguments as unsigned 8-bit integers in the range to 255. Negative 
numbers are treated as the two's complement (for example, -1 is treated as 255). 

3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

220 A* = CHR$(G5) 

230 PRINT CHRiMYALUE) 
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8.0 COMP% 



Function 



The COMP% function compares two numeric strings and returns a minus one, zero, or one, depend- 
ing on the results of the comparison. 

Format 



int-vbl = COMP%(str-exp1 , str-exp2) 



Syntax Rules 

1. Str-exp1 and str-exp2 are numeric strings. They can contain up to 60 ASCII digits and an 
optional decimal point and leading sign. 

General Rules 

1 . If str-exp1 is greater than str-exp2, COMP% returns one. 

2. If the string expressions are equal, COMP% returns zero. 

3. If str-expl is less than str-exp2, COMP% returns minus one. 

4. The value returned by the COMP% function is an integer of the default size. 

Examples 

400 NUM_STRING$ = "35" 

425 OLD _ NUM. STRING* = "33.1" 

450 ALPHA = C0MPX<NUM_STRING$ . OLD. NUM _ STR I NG* ) 
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9 = COS 

Function 

The COS function returns the cosine, in radians, of an angle. 

Format 



real-vbl = COS(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . The returned value is between minus one and one. 

2. BASIC expects the argument of the COS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 

900 COSINE, ALPHA = C0S(PI/2) 
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10.0 CTRLC 

Function 

The CTRLC function enables CTRL/C trapping. When CTRL/C trapping is enabled, a CTRL/C typed 
at the terminal causes control to be transferred to the program's error handler. 

Format 



int-vbl = CTRLC 



Syntax Rules 

None. 

General Rules 

1. After the CTRLC function is invoked, control passes to the error handler when BASIC 
encounters a CTRL/C. If there is no error handler in a program, the program aborts when 
BASIC encounters a CTRL/C. 

2. CTRL/C trapping is asynchronous; that is, BASIC suspends execution and signals 
"Programmable A C trap" (ERR = 28) as soon as it detects a CTRL/C. Consequently, a 
statement can be interrupted while executing. A statement so interrupted may be only 
partially completed and variables may be left in an undefined state. 

3. BASIC can trap more than one CTRL/C error in a program as long as the error does not 
occur while the error handler is executing. If a second CTRL/C is detected while the error 
handler is processing the first CTRL/C, the program aborts. 

RSX 4. On RSX-1 1M/M-PLUS systems, the task that contains the CTRLC function must be able to 

attach to a terminal as soon as the CTRLC function is enabled. If another task is attached to 
the terminal, the task that enabled the CTRLC function terminates with a directive error. 

5. The CTRLC function always returns a value of zero. 
Examples 

10 ON ERROR GOTO 19000 
20 YX = CTRLC 



19000 IF (ERR = 28) THEN Y'Z = CTRLC 
19010 RESUME 



302 BASIC Reference Manual 



CVT$$ 



11 n ci\rr$& 



Function 



The CVT$$ function is identical to the EDIT$ function. See the EDIT$ function for syntax and general 
rules. 

Note 

DIGITAL recommends that you use the EDIT$ function rather than the CVT$$ function 
for new program development. 

Format 



str-vbl = CVT$$(str-exp, int-exp) 



Examples 

100 A* = CyT**(B*>48) 
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12.0 CVTxx 

Function 

Note 

CVT functions are supported only for compatibility with BASIC-PLUS. DIGITAL 
recommends that you use BASIC'S dynamic mapping feature or multiple MAP state- 
ments for new program development. 

The CVT$% function maps the first 2 characters of a string into a 1 6-bit integer. The CVT%$ function 
translates a 16-bit integer into a 2-character string. The CVT$F function maps a 4- or 8-character 
string into a floating-point variable. The CVTF$ function translates a floating-point number into a 4- 
or 8-byte character string. The number of characters translated depends on whether the floating-point 
variable is single- or double-precision. 

Format 



int-vbl = CVT$%(str-vbl) 
str-vbl = CVT%$(int-vbl) 
str-vbi = CVTF$(reai-vbi) 
real-vbl = CVT$F(str-vbl) 





Syntax Rules 

vax^> 1 . In VAX-/ / BASIC, CVT functions reverse the order of the bytes when moving them to or 

from a string. Thus, you can mix MAP and MOVE statements, but you cannot use FIELD 
and CVT functions on a file if you also plan to use MAP or MOVE. 

General Rules 

CVT$% 

1 . If the CVT$% str-vbl has fewer than two characters, BASIC pads the string with nulls. 

vax> 2. In VAX-1 7 BASIC, if the default data type is LONG, only two bytes of data are extracted 

from str-vbl; the high-order byte is sign-extended into a longword. 

3. The value returned by the CVT$% function is an integer of the default size. 

CVT%$ 

1 . Only two bytes of data are inserted into str-vbl. 

2. If you specify a floating-point variable for int-vbl, BASIC truncates it to an integer of the 
default size. If the default size is BYTE and the value of int-vbl exceeds 127, BASIC signals 
an error. 
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1 . CVT$F maps four characters when the program is compiled with /SINGLE and eight char- 
acters when the program is compiled with /DOUBLE. 

2. If str-vbl has fewer than four or eight characters, BASIC pads the string with nulls. 

3. The real-vbl returned by the CVT$F function is of the default floating-point size. In VAX-1 1 
BASIC, if the default size is GFLOAT or HFLOAT, BASIC signals the error "Floating CVT 
illegal for GFLOAT or HFLOAT". 

CVTF$ 

1 . The CVTF$ function maps single-precision numbers to a 4-character string and double- 
precision numbers to an 8-character string. 

2. BASIC expects the argument of the CVTF$ function to be a real-exp. When the argument is 
a real-exp, BASIC returns a value of the same floating-point size. When the argument is not 
a real-exp, BASIC converts the argument to the default floating-point size and returns a 
value of the default floating-point size. In VAX-1 1 BASIC, if the default floating-point size 
is GFLOAT or HFLOAT, BASIC signals the error "Floating CVT illegal for GFLOAT or 
HFLOAT". 

Examples 

10 AX = CVT*Z<EMP_NAME*) 

20 A$ = CUT'I$(AI) 

100 A = CMT$F(EMP.NAME$) 

110 EMP_NAME$ = CMTF$(A) 



Note 

DIGITAL does not recommend the CVTxx functions for new program development. 
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13.0 DATE$ 

Function 

The DATE$ function returns a string containing a day, month, and year in the form dd-Mmm-yy. 
Format 



str-vbl = DATE$(int-exp) 



Syntax Rules 

1 . Int-exp can have up to six digits in the form YYYDDD, where the "Y" characters specify 
the number of years since 1970 and the "D" characters specify the day of that year. 

2. You must fill all three of the "D" positions with digits or zeros before you fill the "Y" 
positions. For example: 

• DATE$(121) returns the date 01-May-70, day 121 of the year 1970. 

• DATE$(1201) returns the date 20-Jul— 71, day 201 of the year 1971. 

• DATE$(12001) returns the date 01-Jan-82, day 1 of the year 1982. 

• DATE$(10202) returns the date 21-Jul-80, day 202 of the year 1980. 

3. If int-exp equals zero, DATE$ returns the current date. 
General Rules 

1 . The str-exp returned by the DATE$ function consists of nine characters and expresses the 
day, month, and year in the form dd-Mmm-yy. 

2. If you specify an invalid date, such as day 385, results are undefined and unpredictable. 

3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

4. On RSTS/E systems, the form of the DATE$ function's output can be changed to ISO 
format, yy.mm.dd, during the installation procedure, or to the format selected by the 
system manager at system start-up time. 

Examples 

500 PRINT DATE(9231) 
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14.0 DECIMAL (VAX-11 BASIC Only) 

Function 

The DECIMAL function converts a numeric expression or numeric string to the DECIMAL data type. 
Format 



decimal-vbl = DECIMAL(exp [, int-const1, int-const2 ] ) 



Syntax Rules 

1 . lnt-const1 specifies the total number of digits (the precision) and int-const2 specifies the 
number of digits to the right of the decimal point (the scale). If you do not specify these 
values, BASIC uses the d (digits) and s (scale) defaults for the DECIMAL data type. 

2. lnt-const1 and int-const2 must be positive integers in the range 1 to 31, inclusive. 
lnt-const2 cannot exceed the value of int-const1 . 

3. Exp can be either a numeric expression or a numeric string. If a numeric string, it can 
contain up to 31 ASCII digits and an optional decimal point and leading sign. 

General Rules 

1. If exp is a string, BASIC ignores leading, trailing, and embedded spaces and tabs. 

2. The DECIMAL function returns a zero when a string argument contains only spaces and 
tabs, or when it is null. 

Examples 

100 INPUT "enter a decimal ualue " JDEC.MALUE 
B = DECIMAL(DEC_UALUE*5»2) 
PRINT B» DECIMAL (HOURLY. PAY) 
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15.0 DET 

Function 

The DET function returns the value of the determinant of the last matrix inverted with the MAT INV 
function. 

Format 



real-vbl = DET 



Syntax Rules 

None. 

General Rules 



1 . When a matrix is inverted with the MAT INV statement, BASIC calculates the determinant 
as a by-product of the inversion process. The DET function retrieves this value. 

2. If your program does not contain a MAT INV statement, the DET function returns a zero. 

3. The value returned by the DET function is a floating-point value of the default floating- 
point size. 



Examples 



100 DETERMINANT = DET 
PRINT DET 
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16.0 DIF$ 

Function 

DIF$ returns a string whose value is the difference between two numeric strings. 

Format 



str-vbl = DIF$(str-exp1 , str-exp2) 



Syntax Rules 

1 . Str-exp 1 and str-exp2 specify the numeric strings you want to process. They can contain up 
to 54 ASCII digits, an optional decimal point, and an optional leading sign. 

General Rules 

1 . BASIC subtracts str-exp2 from str-expl and stores the result in str-vbl. 

2. The difference between two integers takes the precision of the larger integer. 

3. The difference between two decimal fractions takes the precision of the more precise 
fraction, unless trailing zeros generate that precision. 

4. The difference between two floating-point numbers takes precision as follows: 

• The difference of the integer parts takes the precision of the larger part. 

• The difference of the decimal fraction part takes the precision of the more precise part. 

5. BASIC truncates leading and trailing zeros. 

Examples 

500 RESULT* = DIF* < "B776" » "-455") 
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17.0 ECHO 

Function 

The ECHO function causes characters to be echoed at a terminal open on a specified channel. 

Format 



int-vbl = ECHO(chnl-exp) 



Syntax Rules 

None. 

General Rules 

1 . Chnl-exp must specify a terminal. You cannot include a pound sign (#) in chnl-exp. 

2. The ECHO function is the complement of the NOECHO function; that is, ECHO disables 
the effect of ECHO and vice versa. 

3. The ECHO function has no effect on an unopened channel. 

4. The ECHO function always returns a value of zero. 

Examples 

100 Y = ECHQ(O) 
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18.0 EDIT$ 

Function 

The EDITS function performs one or more string editing functions, depending on the value of its 
integer argument. 

Format 



str-vbl = EDIT$(str-exp, int-exp) 



Syntax Rules 

None. 
General Rules 

1 . BASIC edits str-exp to produce str-vbl. 

2. The editing that BASIC performs depends on the value of int-exp. Table 22 describes EDIT$ 
values and functions. 

3. All values are additive; that is, you can perform the editing functions of values 8, 1 6, and 
32 by specifying a value of 56. 

4. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Table 22: EDIT$ Values 



Value 



1 

2 

4 

8 

16 

32 

64 

128 

256 






Discards each character's parity bit (bit 7) 

Discards all spaces and tabs 

Discards all carriage returns, line feeds, form feeds, deletes, escapes, and nulls 

Discards leading spaces and tabs 

Converts multiple spaces and tabs to a single space 

Converts lowercase letters to uppercase letters 

Converts left bracket ([) to left parenthesis [(] and right bracket (]) to right parenthesis [)] 

Discards trailing spaces and tabs (same as TRM$ function) 

Suppresses all editing for characters within quotation marks; if the string has only one quotation mark, BASIC 
suppresses all editing for the characters following the quotation mark 



Examples 



100 



NEW-STRING* = EDIT* < OLD-STRING* , 32 + IB) 
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19.0 ERL 

Function 

The ERL function returns the number of the line where the last error occurred. 

Format 



int-vbl = ERL 



Syntax Rules 

None. 

General Rules 

1 . If the ERL function is used before an error occurs or after BASIC executes a RESUME 
statement, results are undefined. 

2. The ERL function overrides the /NOLINE qualifier. If a program compiled with the 
/NOLINE qualifier in effect contains an ERL function, BASIC signals the message "ERL 
overrides NOLINE". 

3. The int-vbl returned by the ERL function is a WORD integer in BASIC-PLUS-2 and a 
LONG integer in VAX-/ / BASIC. 

Examples 

300 IF (ERL = 20) THEN RESUME 500 



500 PRINT 'Error occurred on line'iERL 
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Function 



The ERN$ function returns the name of the main program, subprogram, or (VAX- 7 7 BASIC only) DEF 
that was executing when the last error occurred. 



Format 



S tr.yb! = ERN$ 



Syntax Rules 

None. 

General Rules 

1. In BASIC-PLUS-2, if the ERN$ function executes before an error occurs, ERN$ is unde- 
fined. When an error occurs, ERN$ is set to the name of the module that caused the error. 

2. On VAX-7 7 systems, if the ERN$ function executes before an error occurs or after BASIC 
executes a RESUME statement, ERN$ returns a nuli string. 

Examples 

2000 PRINT 'Error in modul e ' 5ERN* 
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21.0 ERR 

Function 

The ERR function returns the number of the latest run-time error. 

Format 



int-vbl = ERR 



Syntax Rules 

None. 

General Rules 

1 . If the ERR function is used before an error occurs or after BASIC executes a RESUME 
statement, results are undefined. 

2. The int-vbl returned by the ERR function is always a WORD integer in BASIC-PLUS-2 and 
a LONG integer in VAX-1 I BASIC. 

3. Appendix B in BASIC on VAX/VMS Systems, BASIC on RSX-I / M I M-PLUS Systems, or 
BASIC on RSTS/E Systems lists run-time errors and their numbers. 

Examples 

2000 IF (ERR = 11) THEN RESUME 1000 
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22.0 ERT$ 

Function 

The ERT$ function returns explanatory text associated with an error number. 

Format 



str-vbl = ERT$(int-exp) 



Syntax Rules 

None. 

Genera! Rules 

1 . Int-exp is an error number. It must be between and 255, inclusive. 

2. The ERT$ function can be used at any time to return the text associated with a specified 
error number. 

3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

2020 PRINT 'Error' >ERR. ' on line'JERL 
PRINT ERT$(ERR> 
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23.0 EXP 

Function 

The EXP function returns the value of the mathematical constant "e", raised to a specified power. 

Format 



real-vbl = EXP(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . The EXP function returns the value of "e" raised to the power of real-exp. 

2. When the default size is SINGLE or DOUBLE, EXP allows arguments between -88 and 88, 
inclusive. In VAX-1 1 BASIC, if the default size is GFLOAT, EXP allows arguments in the 
range -709 to 709, inclusive; if the default size is HFLOAT, the arguments can be in the 
range -11356 to 11355. When the argument exceeds the upper limit of a range, BASIC 
signals an error. When the argument exceeds the lower limit of a range, the EXP function 
returns zero and BASIC does not signal an error. 

3. BASIC expects the argument of the EXP function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 

100 A = EXP(4.B) 
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24.0 FIX 



Function 



The FIX function truncates a floating-point value at the decimal point and returns the integer portion 
represented as a floating-point value. 

Format 



real-vbl = FlX(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . The FIX function returns the integer portion of a floating-point value, not an integer value. 

2. BASIC expects the argument of the FIX function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

3. If real-exp is negative, FIX returns the negative integer portion. For example, FIX(-5.2) 
returns -5. 

Examples 

200 FIX.VALUE = FIX<-3.333) 

210 PRINT FlX(Za,5BG) , FIX.MALUE 
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25.0 FORMATS 

Function 

The FORMATS function converts an expression to a formatted string. 

Format 



str-vbl = FORMAT$(exp, str-exp) 



Syntax Rules 

None. 

General Rules 

1 . The rules for building a format string are the same as those for printing numbers with the 
PRINT USING statement. 

Examples 

500 PRINT F0RMAT*< 12345, "#*,*#»") 



318 BASIC Reference Manual 



FSP$ 



26.0 FSP$ 

Function 

The FSP$ function returns a string describing an open file on a specified channel 

Format 



str-vbl = FSP$(chnl-exp) 



Syntax Rules 

1 . A file must be open on chnl-exp. You cannot include a pound sign (#) in chnl-exp. 

2. The FSP$ function must come immediately after the OPEN statement for the file. 

General Rules 

1. In BASIC-PLUS-2, byte 1 returns the RMS record format field (RFM). In VAX-) 1 BASIC, 
byte 1 is undefined. 

2. In BASIC-PLUS-2, bytes 9 and 10 in the returned string contain the RMS Bucketsize (BKS) 
or RMS Blocksize (BLS) for magnetic tape. Byte 12 is the number of indexes (keys) in the 
file. In VAX-11 BASIC, the FSP$ function returns zeros in bytes 9 through 12. 

3. Use the FSP$ function with files opened as ORGANIZATION UNDEFINED. Then use 
multiple MAP statements to interpret the returned data. 

4. See the BASIC User's Guide and the RMS User's Guide for more information on FSP$ 
values. 

Note 

VAX-11 BASIC supports the FSP$ function for compatibility with BASIC-PLUS-2. 
However, you can access the information in bytes 9 through 12 in the returned string 
more efficiently in VAX-1 1 BASIC by using the USEROPEN clause in the OPEN 
statement. 

Examples 

500 A* = FSP*(1) 
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27.0 FSS$ (BASIC-PLUS-2 Only) 

Function 

The FSS$ function scans a file name string beginning at a specified position and returns a 
30-character string describing the file name and status. Because file specifications differ from system 
to system, the returned string contains system-specific information. See BASIC on RSX-1 1M/M-PLUS 
Systems or BASIC on RSTS/E Systems for more information on the values returned by the FSS$ 
function. 

Format 



str-vbl = FSS$(str-vbl, int-vbl) 



Syntax Rules 

1 . Str-vbl names the file name string to be scanned. 

2. Int-vbl specifies the character position at which scanning starts. 

General Rules 

1 . If you specify a floating-point variable for int-vbl, BASIC truncates it to an integer of the 
default size. 

2. Str-vbl is a 30-character string. See BASIC on RSX-1 1M/M-PLUS Systems and BASIC on 
RSTS/E Systems for information on the encoding of str-vbl. 

Note 

VAX-? 7 BASIC does not support the FSS$ function. However, the DEFAULTNAME 
clause in the OPEN statement supplies default file specification components. 

Examples 

100 Y* = FSS*(A*»BZ) 
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Function 

The GETRFA function returns the Record File Address (RFA) of the last record accessed in an RMS file 
open on a specified channel. 

Format 



rfa-vbl = GETRFA(chn!-exp) 



Syntax Rules 

1 . Rfa-vbl is a variable of the RFA data type. 

2. Chnl-exp is the channel number of an open RMS file. You cannot include a pound sign (#) 
in the channel expression. 

3. You must access a record in the file with a GET, FIND, or PUT statement before using the 
GETRFA function, or BASIC signals "No current record" (ERR=131). 

General Rules 

1 . There must be a file open on the specified chnl-exp or BASIC signals an error. 

2. You can use the GETRFA function with RMS sequential, relative, indexed, and (except on 
RSTS/E systems) block I/O files. 

3. The RFA value returned by the GETRFA function can be used only for assignments to and 
comparisons with other variables of the RFA data type. Comparisons are limited to equal to 
( = ) and not equal to (<>) relational operations. 

4. RFA values cannot be printed or used for any arithmetic operations. 
Examples 

100 DECLARE RFA R_ARRAY(99) 



500 FOR IX = IX TO 100Z 
PUT #1 

R_ARRAY(I%) = GETRFA(l) 
NEXT IX 
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29.0 INSTR 

Function 

The INSTR function searches for a substring within a string. It returns the position of the substring's 
starting character. 

Format 



int-vbl = INSTR(int-exp, str-exp1, str-exp2) 



Syntax Rules 

None. 

General Rules 



1. The INSTR function searches str-expl , the main string, for the first occurrence of a 
substring, str-exp2, and returns the position of the substring's first character. 

2. Int-exp specifies the character position in the main string at which BASIC starts the search. 

3. INSTR returns the character position in the main string at which BASIC finds the substring, 
except in the following situations: 

• If only the substring is null, and if int-exp is less than or equal to zero, INSTR returns a 
value of one. 

• If only the substring is null, and if int-exp is equal to or greater than one and less than or 
equal to the length of the main string, INSTR returns the value of int-exp. 

• If only the substring is null, and if int-exp is greater than the length of the main string, 
INSTR returns the main string's length plus one. 

• If the substring is not null, and if int-exp is greater than the length of the main string, 
INSTR returns zero. 

• If only the main string is null, INSTR returns zero. 

• If both the main string and the substring are null, INSTR returns one. 

4. If BASIC cannot find the substring, INSTR returns zero. 

5. If int-exp does not equal one, BASIC still counts from the beginning of the main string to 
calculate the starting position of the substring. That is, BASIC counts character positions 
starting at position one, regardless of where you specify the start of the search. For exam- 
ple, if you specify 1 as the start of the search and BASIC finds the substring at position 1 5, 
INSTR returns the value 15. 

6. If int-exp is less than one, BASIC assumes a starting position of one. 

7. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 
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Note 

VAX-11 BASIC supplies the INSTR function only for compatibility with 
BASIC-PLUS-2 and BASIC-PLUS. DIGITAL recommends that you use the POS func- 
tion for substring searches. 

Examples 

300 Y = INSTRU. ALPHA$ , "JKLMN") 
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30.0 INT 



Function 



The INT function returns the floating-point value of the largest whole number less than or equal to a 
specified expression. 

Format 



real-vbl = INT(real-exp) 



Syntax Rules 

None. 

General Rules 

1. If real-exp is negative, BASIC returns the largest whole number less than or equal to 
real-exp. For example, INT(-5.3) is -6. 

2. BASIC expects the argument of the INT function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

3. This example contrasts the INT and FIX functions: 

10 TEST.NUM = -32.7 

20 PRINT "INT OF -32,7 IS: "5 INT ( TEST.NUM ) 

30 PRINT "FIX DF -32.7 IS: "? FIX ( TEST.NUM ) 

40 END 

RUNNH 

INT OF -32.7 IS: -33 
FIX OF -32.7 IS: -32 

Examples 

650 RESULT = INT(B.B67) 
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31.0 INTEGER 

Function 

The INTEGER function converts a numeric expression or numeric string to a specified or default 
INTEGER data type. 

Format 



int-vbl = INTEGER(exp 



, LONG 
, BYTE 
, WORD 



Syntax Rules 



1. Exp can be either numeric or string. A string expression can contain the ASCII digits 
through 9, a plus sign ( + ), or a minus sign (-). 



General Rules 

1 . BASIC evaluates exp, then converts it to the specified INTEGER size. If you do not specify a 
size, BASIC uses the default INTEGER size. 

2. If exp is a string, BASIC ignores leading and trailing spaces and tabs. 

3. The INTEGER function returns a zero when a string argument contains only spaces and 
tabs, or when it is null. 

Examples 

100 INPUT "Enter a f 1 oat ins-point numbe r" !F_P 
PRINT INTEGER(F_P, WORD) 
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32.0 LEFTS 

Function 

The LEFT$ function extracts a specified substring from a string's left side, leaving the main string 
unchanged. 

Format 



str-vbl = 



LEFT 
LEFT$ 



(str-exp, int-exp) 



Syntax Rules 

None. 

General Rules 

1 . The LEFT$ function extracts a substring from the left of the specified str-exp and stores it in 
str-vbl. 

2. Int-exp specifies the number of characters to be extracted from the left side of the str-exp. 

3. If int-exp is less than one, LEFT$ returns a null string. 

4. If int-exp is greater than the length of str-exp, LEFT$ returns the entire string. 

5. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Note 

VAX-/ 7 BASIC supplies the LEFT$ function only for compatibility with BASIC-PLUS 
and BASIC-PLUS-2. DIGITAL recommends that you use the SEG$ function for sub- 
string extraction. 

Examples 

410 SUB-STRING* = LEFT* ( ALPHA* , 5%) 
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Function 

The LEN function returns an integer value equal to the number of characters in a specified string. 

Format 



int-vbl = LEN(str-exp) 



Syntax Rules 

None. 

General Rules 

1 . If str-exp is null, LEN returns a value of zero. 

2. The length of str-exp includes leading, trailing, and embedded blanks. Tabs in str-exp are 
treated as a single space. 

3. The value returned by the LEN function is an integer of the default size. 
Examples 

200 LENGTH = LENfALPHA*) 
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34.0 LOC (VAX-11 BASIC Only) 

Function 

The LOC function returns a longword integer specifying the virtual address of a simple or subscripted 
variable. For dynamic strings, the LOC function returns the address of the descriptor rather than the 
address of the data. 

Format 



int-vbl = LOC(vbl) 



I 



Syntax Rules 

1 . Vbl can be any local or external, simple or subscripted variable. 

2. Vbl cannot be a virtual array element. 

General Rules 

1 . The LOC function always returns a LONG value. 
Examples 

100 DECLARE LONG B > A 
200 A = L0C(B) 
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35.0 LOG 



Function 



The LOG function returns the natural logarithm (base "e") of a specified number. The LOG function 
is the inverse of the EXP function. 

Format 



real-vbl = LOG(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . Real-exp must be greater than zero. An attempt to find the logarithm of zero or a negative 
number causes BASIC to signal "Illegal argument in LOG" (ERR = 53). 

2. The LOG function uses the mathematical constant "e" as a base. BASIC approximates "e" 
to be 2.718281828459045 (double precision). 

3. The LOG function returns the exponent to which "e" must be raised to equal real-exp. 

4. BASIC expects the argument of the LOG function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 

10 EXPONENT = L0G(100.35) 
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36.0 LOG10 

Function 

The LOG10 function returns the common logarithm (base 10) of a specified number. 

Format 



real-vbl = LOGIO(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . Real-exp must be larger than zero. An attempt to find the logarithm of zero or a negative 
number causes BASIC to signal "Illegal argument in LOG" (ERR = 53). 

2. The LOG10 function returns the exponent to which 10 must be raised to equal real-exp. 

3. BASIC expects the argument of the LOG1 function to be a real-exp. When the argument is 
a real-exp, BASIC returns a value of the same floating-point size. When the argument is not 
a real-exp, BASIC converts the argument to the default floating-point size and returns a 
value of the default floating-point size. 

Examples 

BOO EXP_BASE_10 = L0G10(250) 
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Function 

The MAC function returns a number that equals the absolute value of a specified expression. The 
returned value has the same data type as the expression. 

Format 






Syntax Rules 

None. 

General Rules 

1. The returned value is always greater than or equal to zero. The absolute value of zero is 
zero. The absolute value of a positive number equals that number. The absolute value of a 
negative number equals that number multiplied by minus one. 

2. The MAG function is similar to the ABS function in that it returns the absolute value of a 
number. The ABS function, however, takes a floating-point argument and returns a 
floating-point value. The MAG function takes an argument of any numeric data type and 
returns a value of the same data type as the argument. 

Examples 

100 DECLARE LONG A 
200 PRINT MAG(A) 
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38.0 MAGTAPE 

Function 

The MAGTAPE function permits your program to control unformatted magnetic tape files. 
Format 



int-vbl1 = MAGTAPE(int-const, int-vbl2, chnl-exp) 



Syntax Rules 

1 . Int-const is an integer between 1 and 9, inclusive, that specifies the code for the MAGTAPE 
function you want to perform. Function codes are described in Table 23. See BASIC on 
RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E Systems for more information on mag- 
netic tape function codes. 

2. VAX-/ 7 BASIC supports only function code 3, rewind tape. Table 24 explains how to 
perform other MAGTAPE functions on VAX /VMS Systems. 

3. Int-vbl2 is an integer parameter for function codes 4, 5, and 6. 

• Int-vbl2 for function 4 is a value from 1 to 32767, inclusive, that specifies the number of 
records to skip. 

• Int-vbl2 for function 5 is a value from 1 to 32767, inclusive, that specifies the number of 
records to backspace. 

• Int-vbl2 for function 6 specifies the density and /or parity of the magnetic tape drive. See 
BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E Systems for information on 
setting the density and parity of the magnetic tape drive. 

4. The chnl-exp associated with the magnetic tape must be open. 
Table 23: MAGTAPE Function Codes 



Code 


Meaning 


1 


Rewind and take tape off-line 


2 


Write end-of-file (EOF) mark 


3 


Rewind tape 


4 


Advance tape a specified number of records 


5 


Backspace tape a specified number of records 


6 


Set density and parity 


7 


Return status of tape 


8 


Return characteristics of file open on tape (RSTS/E only) 


9 


Rewind when file is closed (RSTS/E only) 
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1 . You cannot use the MAGTAPE function with RMS files. 

2. Function codes 8 and 9 are valid only on RSTS/E systems. 

3. If int-const equals 1, 2, 3, 6, or 9, int-vbll always equals zero. 

4. If int-const equals 4, int-vbll is an integer of the default size that equals the number of 
records not skipped. 

5. If int-const equals 5, int-vbll is an integer of the default size that equals the number of 
records not backspaced. 

6. If int-const equals 7, int-vbll is a 16-bit integer that reflects the status of the specified 
magnetic tape. See BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E Systems for 
information on bit values and meaning. 

7. If int-const equals 9, int-vbll is a 1 6-bit integer that describes the file characteristics of the 
specified magnetic tape. See the RSTS/E Programming Manual for information on bit 
values and meaning. 

8. On RSTS/E systems, the "rewind when file is closed" function (9) must appear after the Trstsj 
OPEN statement and before the CLOSE statement associated with the specified magnetic 

tape. 

Table 24: Performing MAGTAPE Functions in VAX-11 BASIC 



MAGTAPE Function 


VAX-11 BASIC Actions 


Write EOF 
Skip records 

Backspace 

Set density 

Status 


Close channel 

Perform CETs, ignore data until reaching de- 
sired record 

Rewind tape, perform GETs, ignore data until 
reaching desired record 

Use the DCL MOUNT command qualifiers 
(/DENSITY and /FOREIGN), or the $MOUNT 
system service 

Use the USEROPEN clause in the OPEN state- 
ment to access the RAB$L_STS and the 
RAB$L_STV 



Examples 

200 I = MAGTAPE (1 t0»2) 
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39.0 MAR (VAX-11 BASIC Only) 

Function 

The MAR function returns the current margin width of a specified channel. 

Format 



int-vbl = 



MAR 
MAR% 



(chnl-exp) 



Syntax Rules 

None. 

General Rules 

1 . The file associated with chnl-exp must be open. You cannot include a pound sign (#) in 
chnl-exp. 

2. If chnl-exp specifies a terminal, the MAR function returns zero if you have not set a margin 
width with the MARGIN statement, if you have set a margin width, the MAR function 
returns that number. 

3. The value returned by the MAR function is an integer of the default size. 
Examples 

200 WIDTH = MAR(O) 
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40,0 M(D$ 

Function 

The MID$ function extracts a specified substring from the middle of a string, leaving the main string 
unchanged. 

Format 



str-vbl = 



MID 

MID$ 



(str-exp, int-exp1 , int-exp2) 



Syntax Rules 

None. 



General Rules 



1 . • The MID$ function extracts a substring from str-exp and stores it in str-vbl. int-expl speci- 

fies the position of the substring's first character. Int-exp2 specifies the length of the sub- 
string. 

2. If int-expl is less than one, BASIC assumes a starting position of one. 

3. If Int-expl is greater than the length of str-exp, MID$ returns a null string. 

4. If int-exp2 is greater than the length of str-exp, BASIC returns the string that begins at 
int-expl and includes all characters remaining in the string. 

5. If int-exp2 is less than or equal to zero, MID$ returns a null string. 

6. If you specify a floating-point expression for int-expl or int-exp2, BASIC truncates it to an 
integer of the default size. 

Note 

VAX-11 BASIC supplies the MID$ function only for compatibility with BASIC-PLUS 
and BASIC-PLUS-2. DIGITAL recommends that you use the SEG$ function for sub- 
string extraction. 



Examples 



220 



NEW-STRING* = MID* ( 0LD_STRING$ t 5, 8) 
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41.0 NOECHO 

Function 

The NOECHO function disables echoing of input on a terminal. 

Format 



int-vbl = NOECHO(chnl-exp) 



Syntax Rules 

None. 

General Rules 

1 . Chnl-exp must specify a terminal. You cannot include a pound sign (#) in chnl-exp. 

2. If you specify NOECHO, BASIC still accepts characters typed on the terminal as input, but 
the characters do not echo on the terminal. 

3. The NOECHO function is the complement of the ECHO function; that is, NOECHO dis- 
ables the effect of ECHO and vice versa. 

4. NOECHO always returns zero. 
Examples 

500 Y = NOECHD(O) 
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42.0 NUM 

Function 

The NUM function returns the row number of the last data element transferred into an array by a MAT 
I/O statement. 

Format 



int-vbl = NUM 



Syntax Rules 

None. 

General Rules 

1. NUM returns zero if it is invoked before BASIC has executed any MAT I/O statements. 

2. For a two-dimensional array, NUM returns an integer specifying the row number of the last 
data element transferred into the array. For a one-dimensional array, NUM returns the 
number of elements entered. 

3. The value returned by the NUM function is an integer of the default size. 
Examples 

10 RQW_C0UNT = NUM 
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43.0 NUM2 

Function 

The NUM2 function returns the column number of the last data element transferred into an array by a 
MAT I/O statement. 

Format 



int-vbl = NUM2 



Syntax Rules 

None. 

General Rules 

1 . NUM2 returns zero if it is invoked before BASIC has executed any MAT I/O statements or 
if the last array element transferred was in a one-dimensional list. 

2. The NUM2 function returns an integer specifying the column number of the last data 
element transferred into an array. 

3. The value returned by the NUM2 function is an integer of the default size. 
Examples 

100 COLUMN-COUNT = NUM2 
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44.0 NUM$ 
Function 

The NUM$ function evaluates a numeric expression and returns a string of characters in PRINT 
statement format, with leading and trailing spaces. 

Format 



str-vbl = NUM$(num-exp) 



Syntax Rules 

None. 

General Rules 

1 . If num-exp is positive, the first character in the string expression is a space. If num-exp is 
negative, the first character is a minus sign. 

2. The NUM$ function does not include trailing zeros in the returned string. If all digits to the 
right of the decimal point are zeros, NUM$ omits the decimal point as well. 

3. When num-exp has an integer portion of six digits or less (for example, 1234.567), BASIC 
rounds the number to six digits (1234.57). If num-exp has seven decimal digits or more, 
BASIC rounds the number to six digits and prints it in E format. 

4. When num-exp is between 0.1 and 1, BASIC rounds it to six digits. When num-exp is 
smaller than 0.1, BASIC rounds it to six digits and prints it in E format. 

5. If num-exp is a longword integer, the returned string can have up to 10 digits. 

6. The last character in the returned string is a space. 

Examples 

G60 NUMBER$ = NUM$ ( 34 . 55000 / 32 . 4 > 
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45.0 NUM1$ 

Function 

The NUM1$ function changes a numeric expression to a numeric character string without leading 
and trailing spaces. 

Format 



str-vbl = NUM1$(num-exp) 



Syntax Rules 

None. 

General Rules 

1 . The NUM1 $ function returns a string consisting of numeric characters and a decimal point 
that corresponds to the value of num-exp. Leading and trailing spaces are not included in 
the returned string. 

2. The NUM1$ function returns: 

• Three digits for BYTE integers 

• Five digits for SINGLE floating-point numbers and WORD integers 

• Ten digits for LONG integers 

• Sixteen digits for DOUBLE floating-point numbers 

• Fifteen digits for GFLOAT floating-point numbers {VAX-1 1 BASIC only) 

• Thirty-three digits for HFLOAT floating-point numbers (VAX-1 1 BASIC only) 

3. The NUM1$ function does not produce E notation. 

Examples 

750 NUMBER* = NUM1* ( PI / 2) 
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Function 

The ONECHR function allows single-character input (ODT submode) on a specified channel. This 
function must be used in conjunction with the GET statement. 

Format 



int-vbl = ONECHR(chnl-exp) 



Syntax Rules 

1 . Chnl-exp must refer to an open terminal. You cannot include a pound sign (#) in chnl-exp. 

2. The ONECHR function must be used immediately before the GET statement. 
General Rules 

1 . BASIC disables the ONECHR function immediately after a GET statement executes. There- 
fore, your program must invoke the ONCHR function for each single character input you 
want to perform. 

2. Control passes to the program as soon as you enter a character. You do not have to type a 
line terminator. 

Examples 

100 OPEN "TIs" FOR INPUT AS FILE *1% 

110 Y% = ONECHR(IZ) 

120 GET «U 

MOVE FROM #11, A* = 1% 

PRINT A$ 



Note 

VAX-] 1 BASIC does not support the ONECHR function. To perform this function in 
VAX-1 1 BASIC, you must use the system service SYS$QIO. 
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47.0 PLACES 



Function 



The PLACES function explicitly changes the precision of a numeric string. PLACES returns a numeric 
string, truncated or rounded, according to the value of an integer argument you supply. 



Format 



str-vbl = PLACE$(str-exp, int-exp) 



Syntax Rules 

1. Str-exp specifies the numeric string you want to process. It can contain up to 60 ASCII 
digits and an optional decimal point and leading sign. 

2. If str-exp consists of more than 60 characters, BASIC signals the error "Illegal number" 
(ERR = 52). 

3. Int-exp specifies the numeric precision of str-exp. Table 25 shows examples of rounding 
and truncation and the values of int-exp that produce them. 

General Rules 

1 . Str-exp is rounded and /or truncated according to the value of int-exp. 

2. If int-exp is between -60 and 60, rounding and truncation occur as follows: 

• For positive integer expressions, rounding occurs to the right of the decimal place. For 
example, if int-exp is 1 , rounding occurs one digit to the right of the decimal place (the 
number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the 
right of the decimal place (the number is rounded to the nearest hundredth), and so on. 

• If int-exp is zero, BASIC rounds to the nearest unit. 

• For negative integer expressions, rounding occurs to the left of the decimal point. If 
int-exp is -1, for example, BASIC moves the decimal point one place to the left, then 
rounds to units. If int-exp is -2, rounding occurs two places to the left of the decimal 
point; BASIC moves the decimal point two places to the left, then rounds to tens. 

3. If int-exp is between 9940 and 10060, truncation occurs: 

• If int-exp is 10000, BASIC truncates the number at the decimal point. 

• If int-exp is greater than 10000 (10000 plus n) BASIC truncates the numeric string n 
places to the right of the decimal point. For example, if int-exp is 10001 (10000 plus 1), 
BASIC truncates the number starting one place to the right of the decimal point. If int-exp 
is 10002 (10000 plus 2), BASIC truncates the number starting two places to the right of 
the decimal point, and so on. 
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* it int-exp is less tnan 10000 (10000 minus n), BASiC truncates the numeric string n piaces 
to the left of the decimal point. For example, if int-exp is 9999 (10000 minus 1), BASIC 
truncates the number starting one place to the left of the decimal point. If int-exp is 9998 
(10000 minus 2), BASIC truncates the number starting two places to the left of the 
decimal point, and so on. 

4. If int-exp is not between -60 and 60 or 9940 and 1 0060, BASIC returns zero. 

5. If you specify a floating-point expresstion for int-exp, BASIC truncates it to an integer of the 



default size. 



6. Table 25 shows examples of rounding and truncation and the values of int-exp that pro- 
duce them. The number used is 123456.54321 . 

Examples 

500 NUMBER* = PLACE*(0LD_NUMBER$ t 10001) 
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Table 25: Rounding and Truncation of 123456.654321 



Int-exp 


Effect 


Value Returned 


-5 


Rounded to 100,000s and truncated 


1 


-4 


Rounded to 10,000s and truncated 


12 


-3 


Rounded to 1 000s and truncated 


123 


-2 


Rounded to 1 00s and truncated 


1235 


-1 


Rounded to 10s and truncated 


12346 





Rounded to units and truncated 


123457 


1 


Rounded to tenths and truncated 


123456.7 


2 


Rounded to hundredths and truncated 


123456.65 


3 


Rounded to thousandths and truncated 


123456.654 


4 


Rounded to ten-thousandths and truncated 


123456.6543 


5 


Rounded to hundred-thousandths and truncated 


123456.65432 


9,995 


Truncated to 100,000s 


1 


9,996 


Truncated to 10,000s 


12 


9,997 


Truncated to 1000s 


123 


9,998 


Truncated to 1 00s 


1234 


9,999 


Truncated to 1 0s 


12345 


10,000 


Truncated to units 


1 23455 


10,001 


Truncated to tenths 


12345.6 


10,002 


Truncated to hundredths 


123456.65 


10,003 


Truncated to thousandths 


123456.654 


10,004 


Truncated to ten-thousandths 


123456.6543 


10,005 


Truncated to hundred-thousandths 


123456.65432 
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48.0 POS 

Function 

The POS function searches for a substring within a string and returns the substring's starting character 
position. 

Format 



int-vbl = POS(str-exp1 , str-exp2, int-exp) 



Syntax Rules 

None. 

General Rules 

1 . The POS function searches str-exp 1 , the main string, for the first occurrence of str-exp2, the 
substring, and returns the position of the substring's first character. 

2. Int-exp specifies the character position in the main string at which BASIC starts the search. 

3. If int-exp is greater than the length of the main string, POS returns zero. 

4. POS always returns the character position in the main string at which BASIC finds the 
substring: 

• If only the substring is null, and if int-exp is less than or equal to zero, POS returns a 
value of one. 

• If only the substring is null, and if int-exp is equal to or greater than one and less than or 
equal to the length of the main string, POS returns the value of int-exp. 

• If only the substring is null and if int-exp is greater than the length of the main string, POS 
returns the main string's length plus one. 

• If only the main string is null, POS returns zero. 

• If both the main string and the substring are null, POS returns one. 

5. If BASIC cannot find the substring, POS returns zero. 

6. If int-exp is less than one, BASIC assumes a starting position of one. 

7. If int-exp does not equal one, BASIC still counts from the string's beginning to calculate the 
starting position of the substring. That is, BASIC counts character positions starting at 
position one, regardless of where you specify the start of the search. For example, if you 
specify 10 as the start of the search and BASIC finds the substring at position 15, POS 
returns the value 15. 
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8. If you know that the substring is not near the beginning of the string, specifying a starting 
position greater than one speeds program execution by reducing the number of characters 
BASiC must search. 

9. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

aOO Y = P0B(ALPHA*» "JKLMN" , 1) 
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49.0 PROD$ 

Function 



The PROD$ function returns a numeric string that is the product of two numeric strings. The precision 
of the returned numeric string depends on the value of an integer argument. 



Format 



str-vbl = PROD$(str-exp1 , str-exp2, int-exp) 



Syntax Rules 

1 . Str-exp 7 and str-exp2 specify the numeric strings you want to process. They can contain up 
to 60 ASCII digits and an optional decimal point and leading sign. 

2. If str-exp consists of more than 60 characters, BASIC signals the error "Illegal number" 
(ERR = 52). 

3. Int-exp specifies the numeric precision of str-exp. Table 25 shows examples of rounding 
and truncation and the values of int-exp that produce them. 

General Rules 

1 . Str-exp is rounded and /or truncated according to the value of int-exp. 

2. If int-exp is between -60 and 60, rounding and truncation occur as follows: 

• For positive integer expressions, rounding occurs to the right of the decimal place. For 
example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the 
number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the 
right of the decimal place (the number is rounded to the nearest hundredth), and so on. 

• If int-exp is zero, BASIC rounds to the nearest unit. 

• For negative integer expressions, rounding occurs to the left of the decimal point. If 
int-exp is -1 , for example, BASIC moves the decimal point one place to the left, then 
rounds to units. If int-exp is -2, rounding occurs two places to the left of the decimal 
point; BASIC moves the decimal point two places to the left, then rounds to tens. 

3. If int-exp is between 9940 and 10060, truncation occurs: 

• If int-exp is 10000, BASIC truncates the number at the decimal point. 

• If int-exp is greater than 10000 (10000 plus n), BASIC truncates the numeric string n 
places to the right of the decimal point. For example, if int-exp is 10001 (10000 plus 1), 
BASIC truncates the number starting one place to the right of the decimal point. If int-exp 
is 10002 (10000 plus 2), BASIC truncates the number starting two places to the right of 
the decimal point, and so on. 

(continued on next page) 
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• If int-exp is less than 10000 (10000 minus n), BASIC truncates the numeric string n places 
to the left of the decimal point. For example, if int-exp is 9999 (10000 minus 1), BASIC 
truncates the number starting one place to the ieft of the decimal point. If int-exp is 9998 
(10000 minus 2), BASIC truncates the number starting two places to the left of the 
decimal point, and so on. 

4. If int-exp is not between -60 and 60 or 9940 and 10060, BASIC returns zero. 

5. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

6. Table 25 shows examples of rounding and truncation and the values of int-exp that pro- 
duce them. The number used is 123456.654321. 

Examples 

300 PRODUCT* = PR0D$< "88793" , Z$ t 0) 
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50.0 QUO$ 

Function 

The QUO$ function returns a numeric string that is the quotient of two numeric strings. The precision 
of the returned numeric string depends on the value of an integer argument. 

Format 



str-vbl = QUO$(str-exp1 , str-exp2, int-exp) 



Syntax Rules 

1 . Str-exp1 and str-exp2 specify the numeric strings you want to process. They can contain up 
to 60 ASCII digits and an optional decimal point and leading sign. 

2. If str-exp consists of more than 60 characters, BASIC signals the error "Illegal number" 
(ERR = 52). 

3. Int-exp specifies the numeric precision of str-exp. Table 25 shows examples of rounding 
and truncation and the values of int-exp that produce them. 

General Rules 

1 . Str-exp is rounded and /or truncated according to the value of int-exp. 

2. If int-exp is between -60 and 60, rounding and truncation occur as follows: 

• For positive integer expressions, rounding occurs to the right of the decimal place. For 
example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the 
number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the 
right of the decimal place (the number is rounded to the nearest hundredth), and so on. 

• If int-exp is zero, BASIC rounds to the nearest unit. 

• For negative integer expressions, rounding occurs to the left of the decimal point. If 
int-exp is -1, for example, BASIC moves the decimal point one place to the left, then 
rounds to units. If int-exp is -2, rounding occurs two places to the left of the decimal 
point; BASIC moves the decimal point two places to the left, then rounds to tens. 

3. If int-exp is between 9940 and 10060, truncation occurs: 

• If int-exp is 10000, BASIC truncates the number at the decimal point. 

• If int-exp is greater than 10000 (10000 plus n), BASIC truncates the numeric string n 
places to the right of the decimal point. For example, if int-exp is 10001 (10000 plus 1), 
BASIC truncates the number starting one place to the right of the decimal point. If int-exp 
is 10002 (10000 plus 2), BASIC truncates the number starting two places to the right of 
the decimal point, and so on. 

(continued on next page) 
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• If int-exp is less than 10000 (10000 minus n), BASIC truncates the numeric string n places 
to the left of the decimal point. For example, if int-exp is 9999 (10000 minus 1), BASIC 
truncates the number starting one place to the left of the decimal point, if int-exp is 9998 
(10000 minus 2), BASIC truncates the number starting two places to the left of the 
decimal point, and so on. 

4. If int-exp is not between -60 and 60 or 9940 and 10060, BASIC returns zero. 

5. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

6. Table 25 shows examples of rounding and truncation and the values of int-exp that pro- 
duce them. The number used is 123456.654321. 

Examples 

200 QUOTIENT* = QUO* < "453 . 221 " » "30" , 10000) 
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51.0 RAD$ 

Function 

The RAD$ function converts a specified integer to a 3-character string in Radix-50 format. 

Format 



str-vbl = RAD$(int-vbl) 



Syntax Rules 

None. 

General Rules 

1 . The RAD$ function converts int-vbl to a 3-character string in Radix-50 format and stores it 
in str-vbl. Radix-50 format allows you to store three characters of data as a 2-byte integer. 

2. See Appendix C in BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E Systems for 
information on the Radix-50 character set and ASCII /Radix-50 equivalents. 

3. VAX-11 BASIC supports the RAD$ function, but not its complement, the FSS$ function. <vax 
DIGITAL recommends that you use Run-Time Library routines for Radix-50 operations. 

4. If you specify a floating-point variable for int-vbl, BASIC truncates it to an integer of the 
default size. 

Examples 

100 RADIX* = RAD*C999i 
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52.0 RCTRLC 

Function 

The RCTRLC function disables CTRL/C trapping. 

Format 



int-vbl = RCTRLC 



Syntax Rules 

None. 

General Rules 

1 . After BASIC executes the RCTRLC function, a CTRL/C typed at the terminal returns you to 
command level (BASIC or monitor). 

2. RCTRLC always returns a zero. 
Examples 

200 Y = RCTRLC 
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Function 

The RCTRLO function cancels the effect of a CTRL/O typed on a specified channel. 

Format 



int-vbl = RCTRLO (chnl-exp) 



Syntax Rules 

None. 

General Rules 

1 . Chnl-exp must refer to a terminal. 

2. RCTRLO has no effect if the specified channel is open to a device that does not use the 
CTRL/O convention. 

3. If you type a CTRL/O to cancel terminal output, nothing is printed on the specified termi- 
nal until your program executes the RCTRLO or until you type another CTRL/O, at which 
time normal terminal output resumes. 

4. The RCTRLO function always returns a zero. 
Examples 

10 PRINT "A" FOR IX = IX TO 100% 
YX = RCTRLO(OX) 
PRINT "Normal output is resumed" 
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54.0 REAL 

Function 

The REAL function converts a numeric expression or numeric string to a specified or default floating- 
point data type. 

Format 



real-vbl = REAL(exp 



, SINGLE 




, DOUBLE 


) 


, GFLOAT 


{VAX-11 only) 


, HFLOAT 


(VAX-11 only) 



Syntax Rules 



1 . Exp can be either a numeric expression or a numeric string. If a numeric string, exp can 
contain the ASCII digits through 9, uppercase E, and an optional decimal point and 
leading sign. 



General Rules 



1 . BASIC evaluates exp, then converts it to the specified REAL size. If you do not specify a 
size, BASIC uses the default REAL size. 

2. BASIC ignores leading and trailing spaces and tabs if exp is a string. 

3. The REAL function returns a zero when a string argument contains only spaces and tabs, or 
when the argument is null. 



Examples 

100 INPUT "Enter a numbe r" ; INT_NUM 
PRINT REAL(INT_NUM, DOUBLE) 
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Function 

The RECOUNT function returns the number of characters transferred by the last input operation. 
Format 



int-vbl = RECOUNT 



Syntax Rules 

None. 

General Rules 

1. The RECOUNT value is set by every input operation on any channel, including channel 
zero. 

• After an input operation from your terminal, RECOUNT contains the number of charac- 
ters (bytes), including line terminators, transferred. 

• After accessing a file record, RECOUNT contains the number of characters in the record. 

2. Because RECOUNT is reset by every input operation on any channel, use the RECOUNT 
function to copy the RECOUNT value to a different storage location before executing 
another input operation. 

3. If an error occurs during an input operation, the value of RECOUNT is undefined. 

4. RECOUNT is unreliable after a CTRL/C interrupt because the CTRL/C trap may have 
occurred before BASIC set the value for RECOUNT. 

5. The RECOUNT function returns a LONG value in VAX-1 1 BASIC and a WORD value in 
BASIC-PLUS-2. 

Examples 

200 CHARACTER_COUNT = RECOUNT 

PRINT CHARACTER_CQUNT; ' characters received' 
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56.0 RIGHTS 

Function 

The RIGHTS function extracts a substring from a string's right side, leaving the main string 
unchanged. 

Format 



str-vbl 



RIGHT 
RIGHTS 



(str-exp, int-exp) 



Syntax Rules 

None. 

General Rules 

1. The RIGHT$ function extracts a substring from str-exp and stores the substring in str-vbl. 
The substring begins with the character in the position specified by int-exp and ends with 
the rightmost character in the string. 

2. If int-exp is less than or equal to zero, RIGHTS returns the entire string. 

3. If int-exp is greater than the length of str-exp, RIGHTS returns a null string. 

4. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

600 NEW-STRING* = RIGHT* < ALPHA* » 21) 

Note 

VAX-) 1 BASIC includes the RIGHTS function only for compatibility with BASIC-PLUS 
and BASIC-PLUS— 2. DIGITAL recommends using the SEG$ function for substring 
extraction. 
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57=0 RND 

Functions 

The RND function returns a random number greater than or equal to zero and less than one. 

Format 



real-vbl = RND 



Syntax Rules 

None. 

Genera! Rules 

1. The RND function returns a pseudorandom number if not preceded by a RANDOMIZE 
statement; that is, each time a program runs, BASIC generates the same random number or 
series of random numbers. 

2. If the RND function is preceded by a RANDOMIZE statement, BASIC generates a different 
random number or series of numbers each time a program executes. 

3. In BASIC-PLUS-2, the RND function returns a floating-point value of the default size. In 
VAX-11 BASIC, RND always returns a single-precision value. 

Examples 

990 R_NUM = RND 
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58.0 SEG$ 

Function 

The SEG$ function extracts a substring from a main string, leaving the original string unchanged. 

Format 



str-vbl = SEG$(str-exp, int-exp1, int-exp2) 



General Rules 

1. BASIC extracts the substring from str-exp, the main string, and stores the substring in 
str-vbl. The substring begins with the character in the position specified by int-exp1 and 
ends with the character in the position specified by int-exp2. 

2. If int-expl is less than one, BASIC assumes a value of one. 

3. If int-expl is greater than int-exp2 or the length of str-exp, the SEG$ function returns a null 
string. 

4. If int-expl equals int-exp2, the SEG$ function returns the character at the position specified 
by int-exp 1 . 

5. Unless int-exp2 is greater than the length of str-exp, the length of the returned substring 
equals int-exp2 minus int-expl plus one. If int-exp2 is greater than the length of str-exp, the 
SEG$ function returns all characters from the position specified by int-expl to the end of 
str-exp. 

6. If you specify a floating-point expression for int-expl or int-exp2, BASIC truncates it to an 
integer of the default size. 

Examples 

300 CENTER* = SEG*< ALPHA*, 15 , 20) 
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Function 



The SGN function determines whether a numeric expression is positive, negative, or zero. It returns a 
one if the expression is positive, a minus one if the expression is negative, and zero if the expression 
is zero. 

Format 



int-vbi = SGN(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . If real-exp does not equal zero, SGN returns ABS(rea/-exp)/rea/-exp. 

2. If real-exp equals zero, SGN returns zero. 

3. SGN returns an integer of the default size. 

Examples 

750 SIGN = SGN(-a535/S-3000) 
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60.0 SIN 

Function 

The SIN function returns the sine, in radians, of an angle. 

Format 



real-vbl = SIN(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . The returned value is between minus one and one. 

2. BASIC expects the argument of the ABS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 

100 SI-ANGLE = SINIPI / 2) 
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61.0 SPACES 

Function 

The SPACE$ function creates a string containing a specified number of spaces. 

Format 



str-vbl = SPACE$(int-exp) 



Syntax Rules 

None. 

General Rules 

1 . Int-exp specifies the number of spaces in the returned string. 

2. BASIC treates an int-exp less than zero as zero. 

3. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

880 FILLER* = BPACE$<32) 
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62.0 SQR 

Function 

The SQR function returns the square root of a positive number. 

Format 



real-vbl = 



SORT 

SQR (real-exp) 




;vax; 



Syntax Rules 

None. 

General Rules 



1 . VAX- 7 7 BASIC signals the error "Imaginary square roots" (ERR = 54) and program execu- 
tion stops when real-exp is negative. 

2. BASIC-PLUS-2 returns the warning message "%lmaginary square roots" and the square 
root of the absolute value of the expression when real-exp is negative. The program does 
not stop executing. 

3. BASIC assumes that the argument of the SQR function is a real-exp. When the argument is 
a real-exp, BASIC returns a value of the same floating-point size. When the argument is not 
a real-exp, BASIC returns a value of the default floating-point size. 



Examples 

425 ROOT 



S0R(35*37) 
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63.0 STATUS 

Function 

The STATUS function returns an integer value containing information about the last opened channel. 
Your program can test each bit to determine the status of the channel. 

Format 



int-vbl = STATUS 



Syntax Rules 

None. 

General Rules 



1 . The STATUS function returns a WORD integer in BASIC-PLUS-2 and a LONG integer in 
VAX- 7 7 BASIC. 

2. The value returned by the STATUS function is undefined until BASIC executes an OPEN 
statement. 

3. The STATUS value is set by every input operation on any channel. Therefore, the STATUS 
value should be copied to a different storage location before your program executes 
another input operation. 

4. The syntax for STATUS is the same for VAX-1 1, RSTS/E, and RSX-1 1M/M-PLUS systems. 
However, the returned information is different on every system. 

5. Depending on the error, the STATUS function on RSX-1 7 M I M-PLUS systems displays a ' rsx 
value representing one of the following: ' 

• The RMS-1 1 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS-1 1 MACRO User's Guide for more information. 

• The device characteristics after an RMS-1 1 OPEN file operation (set by the DEV field of 
the FAB). See the RMS-1 1 MACRO User's Guide for more information. 

• The Directive Status Word ($DSW) and its corresponding error code, in the event of a 
directive error. See the RSX-1 1M/M-PLUS Mini Reference for the error codes. 

• The STATUS field of a QIO. See the RSX-1 1M/M-PLUS I/O Drivers Reference Manual 
for more information. 

• The first word of a GETLUN directive describing device characteristics. See the 
RSX-1 1 M I M-PLUS Executive Reference Manual. 

See BASIC on RSX-1 1M /M-PLUS Systems for information on STATUS values set for an 
OPEN file operation with no errors. 
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vVax; 



6. Depending on the error, the STATUS function on RSTS/E systems displays a value repre- 
senting one of the following: 

• The RMS-1 1 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS—1 1 MACRO User's Guide for more information. 

• The device characteristics after an RMS-1 1 OPEN file operation (set by the DEV field of 
the FAB). See the RMS-1 1 MACRO User's Guide for more information. 

For OPEN operations where no errors occur, the status word describes the device charac- 
teristics of the FIRQB and FQFLAG field. The first 7 bits describe the device, and bits 7 
through 15 describe characteristics of the OPEN statement. See the BASIC-PLUS Language 
Manual and the RSTS/E System Directives Manual for more information on STATUS 
values. 

7. In VAX-1 1 BASIC, if an error occurs during an input operation, the value of STATUS is 
undefined. When no error occurs, the six low-order bits of the returned value contain 
information about the type of device accessed by the last input operation. Table 26 lists 
STATUS bits set by VAX-1 1 BASIC. 



Table 26: VAX-1 1 BASIC STATUS Bits 



Bit Set 


Device Type 





Record-oriented device 


1 


Carriage-control device 


2 


Terminal 


3 


Directory device 


4 


Single directory device 


5 


Sequential block-oriented device (magtape) 



Examples 



150 



YX = STATUS 
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Function 



The STR$ function changes a numeric expression to a numeric character string without leading and 
trailing spaces. 

Format 



str-vbl = STR$(num-exp) 



Syntax Rules 

None. 

General Rules 

1 . If num-exp is negative, the first character in the returned string is a minus sign. 

2. Like the NUM$ function, the STR$ function produces E notation. Unlike the NUM$ func- 
tion, the STR$ function does not return leading or trailing spaces. 

3. Like the NUM1$ function, the STR$ function does not return leading or trailing spaces. 
Unlike the NUM1$ function, the STR$ function produces E notation. 

4. When you print a number whose integer portion is six digits or less (for example, 
1 234.567), BASIC rounds the number to six digits (1 234.57). If a number has seven integer 
digits or more, BASIC rounds the number to six digits and prints it in E format. 

5. When you print a number with magnitude between 0.1 and 1 , BASIC rounds it to six digits. 
When you print a number with magnitude smaller than 0.1, BASIC rounds it to six digits 
and prints it in E format. 

Examples 

800 Z$ = STR$(G5) 
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65.0 STRINGS 

Function 

The STRINGS function creates a string containing a specified number of identical characters. 

Format 



str-vbl = STRING$(int-exp1 , int-exp2) 



Syntax Rules 

None. 

General Rules 

1 . Int-exp1 specifies the character string's length. VAX-1 1 BASIC signals the error "String too 
long" (ERR = 227) if int-exp1 is greater than 65535. BASIC-PLUS-2 signals the error 
"Integer error" (ERR = 51) if int-exp is greater than 32767. 

2. If int-exp1 is less than or equal to zero, BASIC treats it as zero. 

3. !nt-exp2 is the decimal ASCI! value of the character that makes up the string. This value is 
treated modulo 256. 

4. BASIC treats all arguments as unsigned 8-bit integers. Negative numbers are treated as the 
two's complement (for example, -1 is treated as 255). 

5. If either int-expl or int-exp2 is a floating-point expression, BASIC truncates it to an integer 
of the default size. 

Examples 

340 A_STRING* = STRING** 10, 65) 
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66.0 SUM$ 

Function 

The SUM$ function returns a string whose value is the sum of two numeric strings. 

Format 



str-vbl = SUM$(str-exp1 , str-exp2) 



Syntax Rules 

1 . Str-expl and str-exp2 specify the numeric strings you want to process. They can contain up 
to 54 ASCII digits and an optional decimal point and leading sign. 

General Rules 

1 . BASIC adds str-exp2 to str-exp1 and stores the result in str-vbl. 

2. If str-expl and str-exp2 are integers, str-vbl takes the precision of the larger string unless 
trailing zeros generate that precision. 

3. If str-expl and str-exp2 are decimal fractions, str-vbl takes the precision of the more precise 
fraction unless trailing zeros generate that precision. 

4. SUM$ omits trailing zeros to the right of the decimal point. 

5. The sum of two floating-point numbers takes precision as follows: 

• The sum of the integer parts takes the precision of the larger part. 

• The sum of the decimal fraction part takes the precision of the more precise part. 

6. SUM$ truncates leading and trailing zeros. 

Examples 

GOO SIGMA$ = SUM*< "234,444" » A*> 
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67.0 SWAP% 

Function 

The SWAP% function transposes a WORD integer's bytes. 

Format 



int-vbl = SWAP%(int-exp) 



Syntax Rules 

1 . SWAP% is a WORD function. BASIC evaluates int-exp and converts it to the WORD data 
type, if necessary. 

General Rules 

1 . BASIC transposes the bytes of int-exp and returns a WORD integer. 

Examples 

500 S_25 = SWAPXO) 
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Function 

The SYS function lets you perform special I /O functions, establish special characteristics for a job, set 
terminal characteristics, and cause the monitor to execute special operations. 

Format 



str-vbl = SYS(str-exp) 



Syntax Rules 



1. Str-exp is a RSTS/E SYS call code. See the RSTS/E Programming Language manual for a 
complete list of SYS call codes and their meanings. 



General Rules 

1 . Because SYS calls request that the RSTS/E monitor perform an operation, often the function 
performed has no counterpart on other host systems. However, for compatibility with 
RSTS/E BASIC-PLUS, VAX-11 BASIC supports a subset of SYS calls. Table 27 lists the 
VAX- 7 J BASIC subset of RSTS/E SYS calls. 

Table 27: VAX-11 BASIC Subset of RSTS/E SYS Calls 



Code 


Function 





Cancel CTRL/O 


1 


Not implemented 


2 


Enable echo 


3 


Disable echo 


4 


Not implemented 


5 


Exit with no prompt 


6 


Call File Processor 


7 


Get core common; can be used only between BASIC images 


8 


Put core common; can be used only between BASIC images 


9 


Exit and clear program 


10 


Reserved 


11 


Cancel type ahead 


12 


Not implemented 


13 


Reserved 


14 


Not implemented 




;vax; 



(continued on next page) 
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SYS 

Table 27: VAX-11 BASIC Subset of RSTS/E SYS Calls (Cont.) 

These FiP caiis (and oniy these) are also supported: 



Code 


Function 


-23 


Terminate file name string scan 


-13 


Set priority (can set only priority; requires ALTPRI privilege) 


-10 


Begin file name string scan 


-7 


Enable CTRL /C trap 


9 


Get error message (VAX-1 1 BASIC error message) 


10 


Assign a device 


11 


Deassign a device 


12 


Deassign all devices 


18 


Send/receive message (requires SYSNAM privilege) 


22 


Send /receive message (cannot get job number, privileges, 
or receive selection; cannot use DECnet; requires PRMMBX 
privilege) 



Examples 



100 OPEN User_keyboard$ AS FILE *1 

200 Tmp* = SYS(CHR*( 11 ) ) ! Cancel any tvpeahead front user 

300 LINUT 'Enter the first line of t ext ' 5Use r_input$ 
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RQfl TAR 



Function 



When used with the PRINT statement, the TAB function moves the cursor or print mechanism right to 
a specified column. 



Format 



str-vbl = TAB(int-exp) 



Syntax Rules 

1 . Int-exp specifies the column number of the cursor or print mechanism. 
General Rules 

1 . You cannot TAB beyond the current MARGIN restriction. 

2. The leftmost column position is zero. 

3. If int-exp is less than the current cursor position, the TAB function has no effect. 

4. The TAB function can move the cursor or print mechanism only from the left to the right. 

5. You can use more than one TAB function in the same PRINT statement. 

6. Use semicolons to separate multiple TAB functions in a single statement. If you use com- 
mas, BASIC moves to the next print zone before executing the TAB function. 

7. The TAB function is valid only for terminals. 

8. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

200 PRINT A*!TAB(15) !B*5TAB(30) ;"HELL0" 
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70.0 TAN 

Function 

The TAN function returns the tangent, in radians, of an angle. 

Format 



real-vbl = TAN(real-exp) 



Syntax Rules 

None. 

General Rules 

1 . BASIC expects the argument of the ABS function to be a real-exp. When the argument is a 
real-exp, BASIC returns a value of the same floating-point size. When the argument is not a 
real-exp, BASIC converts the argument to the default floating-point size and returns a value 
of the default floating-point size. 

Examples 

550 X = TAN<2*PI> 
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71 n TIMP 

■ ■ «W I ■■Vital 



Function 



The TIME function returns the time of day (in seconds) as a floating-point number. On VAX- 7 / and 
RSTS/E systems the TIME function can also return CPU time and device connect time. 



Format 



real-vbl = TIME(int-exp) 



Syntax Rules 

None. 

General Rules 

1 . The value returned by the TIME function depends on the value of int-exp. 

2. If int-exp equals 0, TIME returns the number of seconds since midnight. 

3. BASIC-PLUS-2 on RSX-1 1 M I M-PLUS systems accepts only an argument of zero. All I RSX 

other arguments to the TIME function are undefined and cause BASIC to signal "Not 

implemented" (ERR = 250). 

4. VAX-11 BASIC and BASIC-PLUS-2 on RSTS/E systems also accept arguments from 1 
through 4 and return values as shown in Table 28. All other arguments to the TIME 
function are undefined and cause BASIC to signal "Not implemented" (ERR = 250). 

5. In BASIC-PLUS-2, the TIME function returns a fioating-point vaiue of the default size. In 
VAX-? / BASIC, TIME always returns a single-precision value. 

6. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 
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Table 28: TIME Function Values 



Argument 
Value: 


VAX-11 BASIC 
Returns: 


BASIC-PLUS-2 on 
RSTS/E Systems Returns: 


1 


The current job's CPU time in tenths 
of a second 


The current job's CPU time in tenths 
of a second 


2 


The current job's connect time in 
minutes 


The current job's connect time in 
minutes 


3 


Zero 


Kilo-core ticks 


4 


Zero 


Device time in minutes 



Examples 

150 PRINT TIME(O) 



374 BASIC Reference Manual 



TIMES 



7z.u i iwit$ 

Function 

The TIME$ function returns a string displaying the time of the day. 

Format 



ou-vui — I ilVICvP^HIL-eA^j; 



Syntax Rules 

None. 

General Rules 

1 . If int-exp equals zero, TIME$ returns the current time of day. 

2. Int-exp is the number of minutes before midnight. Str-vb! is the time of day. 

3. The value of int-exp must be in the range to 1440, inclusive, or BASIC signals an error. 

4. In VAX-1 1 BASIC the TIMES function uses a 12-hour, AM/PM clock. Before 12:00 noon, 
TIMES returns HH:MM AM, and after 12:00 noon, HH:MM PM. 

5. In BASIC-PLUS-2 the TIMES function uses either an AM/PM or a 24-hour clock. The 
clock type is an installation option. 

6. On RSTS/E systems only, the clock type can also be set by the system manager at system 
start-up time. 

7. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the 
default size. 

Examples 

200 CURRENT_TIME$ = TIME$(0) 
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TRMS 
73.0 TRM$ 

Function 

The TRM$ function removes all trailing blanks and tabs from a specified string. 

Format 



str-vbl = TRM$(str-exp) 



Syntax Rules 

None. 

General Rules 

1 . The returned str-vbl is the same as str-exp with all the trailing blanks and tabs removed. 

Examples 

BOO NEW_STRING$ = TRM$ ( OLD-STRI NG* ) 



376 BASIC Reference Manual 



VAL 



74.0 VAL 

Function 

The VAL function converts a numeric string to a floating-point value. 

Format 



real-vbl = VAL(str-exp) 



Syntax Rules 

1. Str-exp can contain the ASCII digits through 9, uppercase E, and an optional decimal 
point and leading sign. 

2. BASIC ignores leading, trailing, and embedded spaces and tabs. 
General Rules 

1 . If str-exp is null, or contains only spaces and tabs, VAL returns a zero. 

2. The value returned by the VAL function is of the default floating-point size. 
Examples 

100 REAL.NUM = YAL ( "990 . 32" ) 
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75.0 VAL% 

Function 

The VAL% function converts a numeric string to an integer. 

Format 



int-vbl = VAL%(str-exp) 



Syntax Rules 

1 . Str-exp can contain the ASCII digits through 9 and an optional leading sign. 

2. BASIC ignores leading, trailing, and embedded spaces and tabs. 

General Rules 

1 . If str-exp is null or contains only spaces and tabs, VAL% returns a value of zero. 

2. The value returned by the VAL% function is an integer of the default size. 

3. If str-exp contains a decimal point, BASIC signals the error "Illegal number" (ERR = 52). 

Examples 

100 A - YAL%<"999"> 
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76.0 XLATE 

Function 

The XLATE function translates one string to another by referencing a table string you supply. 

Format 



str-vbl = XLATE(str-exp1 , str-exp2) 



Syntax Rules 

1 . Str-exp1 is the input string. Str-exp2 is the table string, and str-vbl is the returned string. 
General Rules 

1 . Str-exp2 can contain up to 256 ASCII characters, numbered from to 255; the position of 
each character in the string corresponds to an ASCII value. Because zero is a valid ASCII 
value (null), the first position in the table string is position zero. 

2. XLATE scans str-expl character by character, from left to right. It finds the ASCII value n of 
the first character in str-exp1 and extracts the character it finds at position n in str-exp2. 
XLATE then appends the character from str-exp2 to str-vbl. XLATE continues this process, 
character by character, until the end of str-expl is reached. 

3. The output string may be smaller than the input string. 

• XLATE does not translate nulls. If the character at position n in str-exp2 is a null, XLATE 
does not append that character to str-vbl. 

• if the ASCii vaiue of the input character is outside the range of positions in str-exp2, 
XLATE does not append any character to str-vbl. 

Examples 

100 OUTPUT* = XLATE( INPUT** TABLE*) 
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PART VI 

BASIC-PLUS-2 

Debugger Commands 



Note 

This section describes BASIC-PLUS-2 debugger commands. See BASIC on VAX/VMS 
Systems for information on the VAX-1 1 Symbolic Debugger. 

BASIC-PLUS-2 debugger commands help you locate run-time errors and debug program modules 
interactively in the BASIC environment or from monitor level. To use debugger commands, you must 
compile or run at least one program module using the /DEBUG qualifier. 

When you run a task-built program, execution stops at the first line number of the first module 
compiled with the /DEBUG qualifier and control passes to the debugger. When you run a program in 
the BASIC environment, control passes to the debugger when the first line number of the program 
executed with the RUN /DEBUG command is encountered or when the first line number of an object 
module compiled with the /DEBUG qualifier and loaded with the LOAD command is encountered. 

When control passes to the BASIC-PLUS-2 debugger, an identifying message and prompt are 
displayed: 

DEBUGs module -name 



Module-name is the name of the first program module encountered that was compiled with the 
/DEBUG qualifier or executed with the RUN /DEBUG command. The pound sign (#) prompt signals 
you to enter debugger commands. For example: 

•BREAK 300 ® 
•TRACE ® 
•CONTINUE <m> 
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In the example on the previous page, the BREAK command will cause execution to stop at the first 
statement on line 300; the TRACE command will cause the line numbers and statement numbers to 
be displayed as they execute. The CONTINUE command causes the program module to execute until 
line 300; input, output, and the processing proceeds as usual until the breakpoint is reached. When 
the BREAK command has successfully executed, the debugger displays a message identifying your 
current position in the program module and prompts for another debugger command. For example: 

at line 100 statement 1 
at line 100 statement 2 
at line 100 statement 3 
at line 200 statement 1 
at line 200 statement 2 
BREAK at line 300 statement 1 DEBTST 



The identifying message names the debugger command that stopped program execution (BREAK), the 
line number and statement where execution stopped, and the name of the currently executing mod- 
ule (DEBTST in the above example). If the main program is executing, no module name is displayed. 
The # prompt signals you to enter more debugger commands. 

Use the EXIT command to exit from the debugger and end program execution. 

When you compile a program with the /DEBUG qualifier, BASIC links the debugger program module 
from the BASIC-PLUS-2 OTS to your program. This increases the size of your task by at least 4K 
bytes. When you task-build the program, the debugger records are included in the executable task 
image. When you run the executable image, BASIC-PLUS— 2 accesses these records and you can use 
the debugger commands described in the following sections. 

No debugger records are generated for program modules not compiled with the /DEBUG qualifier. 
Thus, you cannot access information, trace module execution, or establish breakpoints in modules 
not compiled with the /DEBUG qualifier. You can, however, use debugger commands to access 
information about the entire task if you compile at least one program module with the /DEBUG 
qualifier. 

After you have debugged your module and changed the source code where necessary, compile the 
module without the /DEBUG qualifier to reduce memory requirements. 

Debugger commands are described on the following pages. All debugger commands except BREAK 
ON can be abbreviated to three letters. 

For an example of a complete debugging session and more information on using the BASIC-PLUS-2 
debugger, see BASIC on RSTS/E Systems or BASIC on RSX-1 1M/M-PLUS Systems. 
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BREAK 



i.u onLMiv (dhoiu- rLuo- £/ 
Function 



The BREAK command lets you stop program execution at program line numbers, particular state- 
ments, or at the beginning of CALL statements, user-defined functions, and FOR, UNTIL, and WHILE 
loops. The program stops before executing the specified breakpoint. 



Format 



BREAK 



ON block 

[ ON ] stmnt-break,. 



block: 



CALL 

DEF 

LOOP 



stmnt-break: lin-num [ .stmnt-num ] [ ;mod-nam ] 



Syntax Rules 



1. The BREAK command with no parameters sets a breakpoint at each line number. The 
program stops at each line number before executing any statements on the line. 

2. Block specifies a block statement. The ON keyword is required. You can specify only one 
block statement in a BREAK ON statement: 

• BREAK ON CALL stops execution each time BASIC executes a CALL statement to a 
subprogram. The program stops before any statements in the subprogram execute. If you 
are executing a task-built program, both the calling and the called program must be 
compiled with the /DEBUG qualifier or the BREAK ON CALL command has no effect. If 
you are executing a program in the BASIC environment, the called program must be 
compiled with the /DEBUG qualifier. 

• BREAK ON DEF stops execution each time BASIC encounters a user-defined function in a 
module compiled with the /DEBUG qualifier. The statement stops before any statements 
in the function execute. 

• BREAK ON LOOP stops execution each time BASIC encounters a FOR, WHILE, or 
UNTIL statement or modifier. The program stops each time the program loops back to 
the loop statement. The program stops after the loop is initialized or incremented, but 
before any statements in the loop execute. 
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3. Stmnt-break specifies a particular line number or statement where execution is to stop. 

• Lin-num specifies a program line. 

• Stat-num specifies a particular statement associated with lin-num. The period (.) is re- 
quired and must immediately follow the line number. BASIC signals an error if you 
include a space between lin-num and stat-num. The cross-reference listing file lists state- 
ments on multi-statement lines by number. 

• Mod-nam specifies that the preceding breakpoint is a breakpoint only in the named 
program module. The semicolon (;) is required. 

• You can specify a maximum of 10 stmnt-break breakpoints. If you specify more than 10 
breakpoints, BASIC signals the error, "No room". 

General Rules 

1 . If you specify a stmnt-break or block that does not exist, no break occurs, BASIC does not 
signal an error or warning, and the program executes normally. 

2. To disable program breakpoints, use the UNBREAK command. 
Examples 

*BREAK 30,2, 500?PR0GB» 2000.3!PR0GC 

•BREAK ON CALL 

#C0N 

BREAK at line 30 statement 2 
* 
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CONTINUE 



o n r*rkMTiMtic /OACir di ne_.o\ 

^■w wviiiiiiwu il*j-i«ji%s — n.i/«j — &i 

Function 

The CONTINUE command continues program execution. 

Format 



CONTINUE 



Syntax Rules 

None 

General Rules 



1. When you have finished entering debugger commands, type CONTINUE to resume pro- 
gram execution. 



Examples 



#BREAK DN LOOP 
*C0N 
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3.0 CORE (BASIC-PLUS-2) 

Function 

The CORE command returns the number of words currently allocated in memory for your entire task. 
Use the CORE command in conjunction with the FREE, STRING, and I/O BUFFER commands to 
determine how memory is allocated for your task. 

Format 



CORE 



Syntax Rules 

None. 

General Rules 

1 . The CORE command displays the total number of words currently allocated to your task. 

2. The maximum allowable program space is 32K words on RSX-1 1M/M-PLUS systems and 
31 K words on RSTS/E systems, minus the size of your resident library. Consult BASIC on 
RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E Systems for more information on program 
space and resident libraries. 

3. You can use the CORE command only when at least one program module has been 
compiled with the /DEBUG qualifier. Note, however, that the number returned by the 
CORE command reflects the memory allocation for the entire task, not just the module 
compiled with /DEBUG. 

4. Knowing the size of core memory can help you control the size of your program and 
optimize accordingly. Consult BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E 
Systems for information on optimization. 

Examples 

#C0RE 

CORE = 7S47 
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ERL 



in FRI /RAQir-PI iiq_o\ 

Function 

The ERL command returns the number of the line executing when the last error occurred. 
Format 



ERL 



Syntax Rules 

None. 

General Rules 

1 . The ERL command tells you the number of the line executing when the last error occurred. 

2. If no errors have occurred, the result returned by ERL is undefined. 
Examples 

#ERL 

ERL = 1050 
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5.0 ERN (BASIC-PLUS-2) 

Function 

The ERN command returns the 1- to 6-character name of the program module that was executing 
when the last successfully handled error occurred. If a fatal error was not successfully trapped, 
control passes from the debugger to command level. 

Format 



ERN 



Syntax Rules 

None. 

General Rules 

1. The ERN command returns a module name only when an error has been successfully 
handled. 

2. If no errors have occurred, the result returned by ERN is undefined. 
Examples 

*ERN 

ERN* = CHECKS 
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en cdd /DACtr m ne o\ 

vmw kirn yi_mOi\s — rbug~£i 

Function 

The ERR command returns the error number of the last error that occurred. 

Format 



ERR 



Syntax Rules 

None. 

General Rules 

1 . The ERR command tells you the number of the last error. 

2. If no errors have occurred, the result returned by ERR is undefined. 

3. Refer to Appendix B in BASIC on RSTS/E Systems or BASIC on RSX-1 1M/M-PLUS Systems 
for a list of errors and their numbers. 

Examples 

*ERR 

ERR = 55 
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7.0 EXIT (BASIC-PLUS-2) 

Function 

The EXIT command returns control to BASIC if you are executing a program in the BASIC environ- 
ment and to command level if you are executing a task-built program. 

Format 



EXIT 



Syntax Rules 

None. 

General Rules 

1 . The EXIT command does not close open channels. 

Examples 

• EXIT 
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8.0 FREE (BASIC-PLUS-2) 

Function 

The FREE command returns the number of words currently available in memory for I/O and string 
operations before BASIC must perform another memory extension. Use the FREE command in con- 
junction with the CORE, STRING, and I/O BUFFER commands to determine how memory is allo- 
cated for your task. 

Format 



FREE 



Syntax Rules 

None. 

General Rules 



1 . The FREE command returns an integer corresponding to the number of free words available 
in memory for I/O and string operations. 

2. When string or I/O operations exceed the available free space, BASIC extends the amount 
of memory allocated for your task. 

3. Knowing the amount of free space available can help you control the size of your program 
and optimize accordingly. Consult BASIC on RSX-11M/M-PLUS Systems or BASIC on 
RSTS/E Systems for information on optimization. 



Examples 

"FREE 

FREE = 184 
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9.0 I/O BUFFER (BASIC-PLUS-2) 

Function 

The I /O BUFFER command returns the number of words currently allocated for I /O buffer space. Use 
the I/O BUFFER command in conjunction with the CORE, STRING, and FREE commands to deter- 
mine how memory is allocated for your task. 

Format 



I/O BUFFER 



Syntax Rules 

None. 

General Rules 



1. The I/O BUFFER command tells you the total number of words allocated for I/O buffer 
space. 

2. Knowing the size of the I/O buffer can help you control the size of your program and 
optimize accordingly. Consult BASIC on RSX-1 1M/M-PLUS Systems or BASIC on RSTS/E 
Systems for information on optimization. 



Examples 



#1 /0 BUFFER 

I /0 BUFFERS = 1765 
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10.0 LET (BAS1C-PLUS-2) 

Function 

The LET command allows you to change the contents of program variables. 

Format 




Syntax Rules 

1 . Vbl1 specifies the numeric or string variable you want to change. If you attempt to create a 
new variable with the LET command, BASIC signals "illegal syntax in LET". 

2. Const or vbl2 specifies the new value for vbll. The LET command allows constants or 
variables as arguments but does not allow expressions. 

3. You cannot set string variables to a null string with the LET command. If you try to do so, 
BASIC signals "Illegal syntax in LET". However, you can set a variable to the null string in 
your source program and then assign that variable to another variable with the LET 
debugger command. For example: 

1000 NULL$= "" 
1010 A*="HELL0" 
1020 PRINT A$ 

Compile or run the program with the /DEBUG qualifier, establish a breakpoint at line 
1020, and set A$ to the null string with the LET command: 

BREAK at line 1020 
*LET A* = NULL* 

General Rules 

1. You can change only one variable with each LET command. To change more than one 
program variable, you must enter more than one LET command. 

2. When executing a task-built program, you can change program variables only in program 
modules compiled with the /DEBUG qualifier. 

3. You cannot access program variables across program modules. That is, you cannot access 
a variable in SUB1 from the main program or from another subprogram, and you cannot 
access a variable in the main program from a subprogram. 

4. BASIC signals "Illegal syntax in LET" when you try to access a variable across modules or 
in a module not compiled with the /DEBUG qualifier. 
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Examples 

•LET As=i5% 

*LET NAME*=" MITCHELL" 

* 
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11.0 PRINT (BASIC-PLUS-2) 

Function 

The PRINT command allows you to display the current contents of program variables. 

Format 



PRINT vbl 



Syntax Rules 

1 . Vbl specifies the numeric or string variable you want to display. 

2. The PRINT command does not allow constants or expressions as arguments. 
General Rules 

1 . You can display only one variable with each PRINT command. To display more than one 
program variable, you must enter more than one PRINT command. 

2. When executing a task-built program, you can access only those variables contained in 
program modules that have been compiled with the /DEBUG qualifier. 

3. You cannot access variables across program modules. That is, the variable you want to 
display must exist in the current program module. If you try to display a variable in another 
program module, BASIC signals "Illegal syntax in PRINT". 

Examples 

#PRINT C 
23 
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12.0 RECOUNT (BASIC-PLUS-2) 

Function 

The RECOUNT command tells you how many characters were transferred by the last I /O operation. 

Format 



RECOUNT 



Syntax Rules 

None. 

General Rules 

1. The RECOUNT command tells you how many characters, including blanks and termina- 
tors, were transferred by the last input or output statement. 

2. If your program has open files and reaches the end of the file before closing open channels 
or executing the END statement, the debugger signals "End-of-file on device". If you then 
try to continue program execution by typing the CONTINUE command, the debugger 
signals "Can't CONTINUE or STEP". When you then EXIT the debugger mode, files are not 
closed, and data is not transferred. If you include an error handler to pass control to the 
END statement, BASIC will close files and transfer data. 

Examples 

•RECOUNT 

RECOUNT = 19 
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13.0 REDIRECT (BASIC-PLUS-2* 

Function 

The REDIRECT command allows you to direct all debugging I/O operations to a specified terminal. 

Format 



REDIRECT term-nam 



Syntax Rules 



1 . Term-nam specifies the name of an unattached terminal. It must be an unquoted string that 
corresponds to a terminal name, or BASIC signals the error "Cannot open device". 

General Rules 

1 . After you type the REDIRECT command in response to the debugger prompt, all debugger 
I/O is directed to the terminal you specify. The program executes on the terminal that 
issued the RUN command. 

2. Use another REDIRECT command to direct debugger I/O back to the terminal on which 
the program is executing. 

3. You can use the REDIRECT command only when at least one program module has been 
compiled with the /DEBUG qualifier. 

4. If the specified terminal is allocated, the debugger will signal "Cannot open device" on 
RSTS/E systems. On RSX-1 7 M I M-PLUS systems, the debugger stops executing until the 
specified terminal is available and does not signal an error. 

Examples 

•REDIRECT KBZ: 
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14.0 STATUS (BASIC-PLUS-2) 

Function 

The STATUS command returns a word-length integer that contains information about the last opened 
file. 

Format 



STATUS 



Syntax Rules 

None. 

General Rules 

1 . The debugger returns the last STATUS word. 

RSX 2. Depending on the error, the STATUS word on RSX-1 1M/M-PLUS systems displays a value 

representing one of the following: 

• The RMS-1 1 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS—1 1 MACRO User's Guide for more information. 

• The device characteristics after an RMS-1 1 OPEN file operation set by the DEV field of 
the FAB. See the RMS-1 1 MACRO User's Guide for more information. 

• In the event of a directive error, the Directive Status Word ($DSW) and its corresponding 
error code. See the RSX-1 1M/M-PLUS Mini Reference for the error codes. 

• The STATUS field of a QIO. See the RSX-11M/M-PLUS I/O Driver's Reference Manual 
for more information. 

• The first word of a GETLUN directive describing device characteristics. See the 
RSX-1 1 M I M-PLUS Executive Reference Manual for more information. 

• See BASIC on RSX-1 1 M / M-PLUS Systems for information on STATUS values set for an 
OPEN file operation with no errors. 

Trstsj 3. Depending on the error, the STATUS word on RSTS/E systems displays a value representing 

— one of the following: 

• The RMS-1 1 primary status field (STS) or the RMS secondary status field (STV). See the 
RMS-1 1 MACRO User's Guide for more information. 

• The device characteristics after an RMS-1 1 OPEN file operation set by the DEV field of 
the FAB. See the RMS-1 1 MACRO User's Guide for more information. 

• For OPEN operations where no errors occur, the status word describes the device charac- 
teristics of the FIRQB and FQFLAG field. The first 7 bits describe the device, and bits 7 
through 15 describe characteristics of the OPEN statement. See the BASIC-PLUS 
Language Manual and the RSTS/E System Directives Manual for more information on 
STATUS values. 
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#STATUS 
STATUS = 31 
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15.0 STEP (BASIC-PLUS-2) 

Function 

The STEP command causes the program module to execute statement by statement, stopping after a 
specified number of statements have executed. 

Format 



STEP [ int-const ] 



Syntax Rules 



1 . Int-const specifies the number of statements to be executed before the program stops. It 
must be a positive integer from 1 to 32767. 

2. STEP with no int-const is the same as specifying STEP 1 . Only one statement executes and 
the program then stops. 

3. If you do not include a space between the command and the int-const, only one statement 
executes. 



Genera! Rules 



1 . When executing a task-built program, only statements in program modules compiled with 
the /DEBUG qualifier in effect are counted. If a module not compiled with the /DEBUG 
qualifier executes before a module compiled with the /DEBUG qualifier, the program does 
not stop until the specified number of statements in the module compiled with /DEBUG 
have executed. 

2. Typing a carriage return in response to the # prompt is the same as typing STEP 1 or STEP 
with no int-const. The next statement executes and the program stops. 

3. Typing a line feed in response to the # prompt has no effect. The debugger waits for a 
carriage return and then signals an error. 



Examples 



BREAK at line 1050 statement 1 

*STEP 2 

*C0N 

STEP at line 1050 statement 3 

« 
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STRING 



16=0 STRING (BASIG-PLUS-2) 

Function 

The STRING command tells you how many words are currently allocated for string storage. Use the 
STRING command in conjunction with the CORE, I/O BUFFER, and FREE commands to determine 
how memory is allocated for your task. 

Format 



bIMIINU 



Syntax Rules 

None. 

General Rules 



1. The STRING command tells you how many words are allocated for string operations for 
your entire task, not just for the currently executing program module. 

2. Knowing how much memory is allocated to string operations can help you control the size 
of your program and optimize accordingly. See BASIC on RSX-1 1M/M-PLUS Systems or 
BASIC on RSTS/E Systems for information on optimization. 



Examples 



3STRING 
STRING = 208B 
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TRACE 

17.0 TRACE (BASIC-PLUS-2) 

Function 

The TRACE command displays line numbers and statement numbers as the program executes. 

Format 



TRACE 



Syntax Rules 

None. 

General Rules 

1 . The TRACE command does not affect program execution or breakpoints. 

2. When executing a task-built program, you can use the TRACE command only in program 
modules that have been compiled with the /DEBUG qualifier. 

3. The TRACE command remains in effect until the program module finishes executing, until 
you specify UNTRACE after a program breakpoint, or until BASIC reaches a module not 
compiled with the /DEBUG qualifier. When BASIC returns to a module compiled with 
DEBUG, tracing resumes. 

Examples 

•TRACE 
•BREAK 300 

• CONT 

at line 100 statement 1 
at line 100 statement 2 
at line 200 statement 1 
BREAK at line 300 statement 1 
•BREAK 500 

• CQNT 
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UNBREAK 



1ft n I IMRDP AIT tO. ACISV-DI 1 IC o\ 

Function 

The UNBREAK command disables previously set breakpoints in programs and subprograms. 
Format 



UNBREAK 


ON block I 




[ ON ] stmnt-break,... I 




CALL 




block: 


DEF 
LOOP 




stmnt-t 


treak: 


lin-num 


[ .stmnt-num 



Syntax Rules 



1. 



The ON keyword is required to disable block breakpoints. 



2. UNBREAK with no parameters disables all previously specified stmnt-break breakpoints. 
Block breakpoints are not disabled. 

3. Stmnt-break specifies a particular line number or statement where execution is to stop. 

• Lin-num specifies a program line. 

• Stat-num specifies a particular statement associated with lin-num. The period (.) is re- 
quired and must immediately follow the line number. BASIC signals an error if you 
include a space between lin-num and stat-num. The listing file lists statements on multi- 
statement lines by number. 

• Mod-nam specifies that the preceding breakpoint is a breakpoint only in the named 
program module. The semicolon (;) is required. 

• You can disable more than one stmnt-break breakpoint with the UNBREAK command, 
but you must separate them with commas. 

• Mod-nam specifies a program module compiled with the /DEBUG qualifier in effect 
When mod-nam is specified, the line number specified is disabled as a breakpoint only 
in the named program. If the breakpoint has not been previously set, BASIC signals an 
error. 

• If lin-num or stat-num do not exist, the debugger signals the error "Bad line spec in 
(UN)BREAK". ^ 
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UNBREAK 



General Rules 

None. 

Examples 

*UNBREAK ON LOOP 

*UNBREAK lOOiGAMES, 500. 600,2 

«C0N 
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UNTRACE 



I ».U UN I HMLC (BA5IU-KLUS-Z) 

Function 

The UNTRACE command disables the TRACE command. 

Format 



UNTRACE 



Syntax Rules 

None. 

General Rules 



1. Enter the UNTRACE command when the program stops executing after encountering a 
specified breakpoint. 



Examples 

•UNTRACE 
*CON 
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Appendix A 

Reserved BASIC Keywords 



%ABORT 


BACK 


CTRLC 


ERT$ 


%CDD 


BASE 


CVT$$ 


ESC 


%CROSS 


BEL 


CVT$% 


EXIT 


%ELSE 


BINARY 


CVT$F 


EXP 


%END 


BIT 


CVT%$ 


EXPLICIT 


%FROM 


BLOCK 


CVTF$ 


EXTEND 


%IDENT 


BLOCKSIZE 


DAT 


EXTENDSIZE 


%IF 


BS 


DAT$ 


EXTERNAL 


%INCLUDE 


BUCKETSIZE 


DATA 


FF 


%LET 


BUFFER 


DATES 


FIELD 


%LIST 


BUFSIZ 


DECIMAL 


FILE 


%NOCROSS 


BY 


DECLARE 


FILESIZE 


%NOLIST 


BYTE 


DEF 


FILL 


%PAGE 


CALL 


DEFAULTNAME 


FILLS 


%SBTTL 


CASE 


DEL 


FILL% 


%THEN 


CCPOS 


DELETE 


FIND 


%TITLE 


CHAIN 


DESC 


FIX 


%VARIANT 


CHANGE 


DET 


FIXED 


ABORT 


CHANGES 


DIF$ 


FLUSH 


ABS 


CHECKING 


DIM 


FNAMES 


ABS% 


CHR$ 


DIMENSION 


FNEND 


ACCESS 


CLK$ 


DOUBLE 


FNEXIT 


ACCESS% 


CLOSE 


DOUBLEBUF 


FOR 


ACTIVE 


CLUSTERSIZE 


DUPLICATES 


FORMATS 


ALIGNED 


COM 


DYNAMIC 


FORTRAN 


ALLOW 


COMMON 


ECHO 


FREE 


ALTERNATE 


COMP% 


EDITS 


FROM 


AND 


CON 


ELSE 


FSP$ 


ANY 


CONNECT 


END 


FSSS 


APPEND 


CONSTANT 


EQ 


FUNCTION 


AS 


CONTIGUOUS 


EQV 


FUNCTIONEND 


ASC 


COS 


ERL 


FUNCTIONEXIT 


ASCII 


COT 


ERN$ 


GE 


ATN 


COUNT 


ERR 


GET 


ATN2 


CR 


ERROR 


GETRFA 
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GFLOAT 

GO 

GOBACK 

GOSUB 

GOTO 

GROUP 

GT 

HFLOAT 

HT 

IDN 

IF 

IFEND 

IFMORE 

IMAGE 

IMP 

INACTIVE 

INDEXED 

INPUT 

INSTR 

INT 

INTEGER 

INV 

INVALID 

ITERATE 

KEY 

KILL 

LEFT 

LEFT$ 

LEN 

LET 

LF 

LINE 

LINO 

LINPUT 

LIST 

LOC 

LOCKED 

LOG 

LOG10 

LONG 

LSET 

MAG 

MAGTAPE 

MAP 

MAR 

MAR% 

MARGIN 

MAT 

MAX 

MID 

MID$ 

MIN 

MOD 

MOD% 

MODE 

MODIFY 

MOVE 

NAME 



NEXT 


RETURN 


UNTIL 


NOCHANGES 


RFA 


UPDATE 


NODATA 


RIGHT 


USAGES 


NODUPLICATES 


RIGHTS 


USEROPEN 


NOECHO 


RND 


USING 


NOEXTEND 


ROUNDING 


USR$ 


NOMARGIN 


RSET 


VAL 


NONE 


SCALE 


VAL% 


NOPAGE 


SCRATCH 


VALUE 


NOREWIND 


SEG$ 


VARIABLE 


NOSPAN 


SELECT 


VARIANT 


NOT 


SEQUENTIAL 


VFC 


NUL$ 


SETUP 


VIRTUAL 


NUM 


SGN 


VPS% 


NUM$ 


SI 


VT 


NUM1$ 


SIN 


WAIT 


NUM2 


SINGLE 


WHILE 


ON 


SIZE 


WINDOWSIZE 


ONECHR 


SLEEP 


WORD 


ONERROR 


SO 


WRITE 


OPEN 


SP 


XLATE 


OPTION 


SPACES 


XOR 


OR 


SPAN 


ZER 


ORGANIZATION 


SPEC% 




OTHERWISE 


SQR 




OUTPUT 


SQRT 




OVERFLOW 


STATUS 




PAGE 


STEP 




PEEK 


STOP 




PI 


STR$ 




PLACES 


STREAM 




POS 


STRING 




POS% 


STRINGS 




PPS% 


SUB 




PRIMARY 


SUBEND 




PRINT 


SUBEXIT 




PROD$ 


SUBSCRIPT 




PUT 


SUMS 




QUO$ 


SWAP% 




RAD$ 


SYS 




RANDOM 


TAB 




RANDOMIZE 


TAN 




RCTRLC 


TEMPORARY 




RCTRLO 


TERMINAL 




READ 


THEN 




REAL 


TIM 




RECORD 


TIME 




RECORDSIZE 


TIMES 




RECORDTYPE 


TO 




RECOUNT 


TRM$ 




REF 


TRN 




REGARDLESS 


TYP 




RELATIVE 


TYPE 




REM 


TYPES 




REMAP 


UNALIGNED 




RESET 


UNDEFINED 




RESTORE 


UNLESS 




RESUME 


UNLOCK 
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Appendix B 

r~ro€jr3iTi 3iivi oUDprccjrsrn \sOGsncj Conventions 



This appendix presents a suggested format for coding BASIC programs. The recommended program 
order and documenting procedures clarify the program's history, purpose, and logical development. 
This organization also helps the program to run faster and with fewer errors. 

This format is by no means intended to represent the only way of coding BASIC programs. It is a 
sample format that can be adapted and modified to suit individual applications. 

10 XTITLE "<module-name> - <terse functional desc ript ion>" 
ZSBTTL "Overall description and Modification history" 
XIDENT "X00.00" 

COPYRIGHT (c) 1982 BY 
DIGITAL EQUIPMENT CORPORATION* MAYNARD , MASS, 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND 
COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH 
THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY 
OTHER COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAIL- 
ABLE TO ANY OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFT- 
WARE IS HEREBY TRANSFERRED. 

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NO- 
TICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIP- 
MENT CORPORATION. 

DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 
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+ + 

FACILITY: 

<Faci 1 i ty name > 

ABSTRACT: 

A short 3-6 line abstract of the function of the Module. If a 
full functional specification can be given in 3-G lines* replace 
"ABSTRACT" above by "FUNCTIONAL DESCRI PTIDN * " and delete the 
"FUNCTIONAL DESCRIPTION" section below. 
! S [Margins and tabs] i 

ENVIRONMENT: 

[Pick one : ] 

PDP-11 user mode [with <Operating system) dependencies] 

VAX-11 user mode. 

PDP-11 and VAX-11 user Mode. 

AUTHDR: <Your name>t CREATION DATE: <dd Hmmmmmiiimm yyyy> 

MODIFIED BY: 

<Your name>* <dd-Mmm-yy>: VERSION X00.00 
OOO - Original version of Module. 



XSBTTL "Full description' 



[Pick at Most 
either. For 
paramete rs . ] 
FUNCTION <datatype> <name> 
SUB <name> 

(<datatype> <param>* 
<datatype> <paraM>) 



one of FUNCTION or SUB below. Include parameters on 
main proiramst oMit FUNCTION or SUB statement and 



! <Description> 
! <Description> 



+ + 

FUNCTIONAL DESCRIPTION: 

A detailed functional description of the routine. This should 
detail the steps of the process* the use of external functions 
and subprograms (including system services) RTL routines* SYSLIB 
routines)* and so forth. 
! ! [Margins and tabs] ! 

FORMAL PARAMETERS: 



<naMe>.<access typeXdata type>.<arg mechXarg forM> 
A description of the meaning of the parameter* 



values* etc. Repeat for 
rather than a function 
STRUCTURE section, 
<access type) is m* r» or 
<datatype> is b> d» g* h» 

GFLOAT * HFLOAT . LONG 

(STRING) » or WORD. 
<arg mech> is d* r* or v for BY DESC 
<arg form> is <null> or a for scalar 
! ! [margins and tabs] 



each parameter. If a 
or subroutine* use 



its legal 
main prog raM 
the COMMAND 



for modify* read* or write, 
p* s. t» or w for BYTE* DOUBLE* 
packed (DECIMAL)* SINGLE* text 



• BY REF. or BY VALUE, 
or array. 
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IMPLICIT INPUTS: 

Describe all uses of the values of Global storage objects used 

by the rout ine » 

! i [margins and tabs] ! 

IMPLICIT OUTPUTS: 

Describe all modifications to the values of Global storase ob- 
jects used by the routine, 
! ! [margins and tabs] { 

FUNCTION VALUE: 
COMPLETION CODES: 

If a function* describe the value returned. If the value re- 
turned is a status indicator* use COMPLETION CODE and delete 
FUNCTION VALUE? if the result of some computation* use FUNCTION 
VALUE and delete COMPLETION CODE, 

If a SUB. delete FUNCTION VALUE and enter "None," 
! I [margins and tabs] ! 

SIDE EFFECTS: 

Describe all functional side effects that are not evident from 
the invocation interface. This includes changes in storage al- 
location* process status* file operations (including the command 
terminal)* errors signalled* etc, 
! ! [margins and tabs] ! 



%SBTTL "Declarations" 

ENVIRONMENT SPECIFICATION: 

OPTION 8. 

<optionclause>» 8, 

<option clause) 

DATATYPE SPECIFICATION: 

RECORD <name> ! <Desc r i Pt i on > 

{ record declaration) 
END RECORD 

! INCLUDE FILES: 

^INCLUDE "<Filespec>" 
! 

! EQUATED SYMBOLS: 
! 

DECLARE {datatype) CONSTANT 8= 

< n am e)=< value)* !<Description) & 

<name> = <value) ! <Desc ript ion) 

LOCAL STORAGE: 

DECLARE & 

<datatype) & 

< n a m e ) * ! {Description) & 

<name)> ! {Description) & 

{datatype) 8c 

{name)* ! {Description) 8: 

{name) !{DescriPtion) 

i 
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! GLOBAL STORAGE: 
! 

COMMON <(name>> 
(datatype) 

(nante) » 

(name ) t 
(datatype) 

<name > » 

(name) 
MAP ((name)) 

(datatype) 

(name > » 

(name) » 
(datatype) 

< name > > 

(name) 

EXTERNAL REFERENCES! 

EXTERNAL <datatype> CONSTANT 

(name > 
EXTERNAL <datatype> 

(name) 
EXTERNAL <datatype> FUNCTION 
< name > 

(<datatype> BY (mech)» 
(datatype) BY (rnech)) 
EXTERNAL SUB 
<name > 

((datatype) BY (wech)t 
<datatype> BY (rnech)) 



INTERNAL REFERENCES: 

DECLARE (datatype) FUNCTION 
< name > 

((datatype) » 
(datatype > ) 



! (Description) 



(Desc ript 
(Descript 

(Desc ri pt 
(Desc ript 
(Descript 

(Desc ript 
(Desc ript 



on) 
on) 

on ) 
on) 
on ) 

on) 
on) 



! (Description) 
! (Desc ript ion) 



! (Description) 

! (Description) 

(Function description) 
(Argument description) 
(Argument description) 

(Function description) 
(Argument description) 
(Argument description) 



(Func t i on 
(Argument 
(Argument 



description) 
description) 
descript ion) 



ZSBTTL ' 
+ 

Set 



Environment initialization' 
up Global error handler 



ON ERROR GO TO 31000 

[Alternately) local error handlers can be 
ZSBTTL "(Major section name)" 
(Major section name): 
! + 

(Section description) 



[Repeat once for each major 
XSBTTL "Internal subroutine; 
[Access via GOSUB (symbolic 
( symbol ic name ) : 

! + 



FUNCTIONAL DESCRIPTION: 
IMPLICIT INPUTS: 
IMPLICIT OUTPUTS: 



section.] 

( symbo lie 
name ) ] 



name)" 



& 
& 

& 

& 

& 
& 
& 
8= 
& 



& 
& 
& 



set up where needed.] 
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30000 



31000 



327G7 



SIDE EFFECTS: 



RETURN 

%SBTTL "Internal function - <name>" 
CAccess via <nane> (< params >) 3 
DEF <datatype> <name> 



(<datatype> <name>» 
(datatype) <name>) 



FUNCTIONAL DESCRIPTION: 
FORMAL PARAMETERS: 
IMPLICIT INPUTS: 
IMPLICIT OUTPUTS: 
FUNCTION VALUE: 
SIDE EFFECTS: 



END DEF 

XSBTTL "RSTS/E CCL entry point" 
[This section is for RSTS/E CCL's only] 
+ 

CCL entry point: 

%SBTTL "Common error handling" 

+ 

Common error handling: 

ZSBTTL "Module end" 

END (FUNCTION, null, or SUB> 



<Desc ript i on> 
(Description) 
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The Master Index contains a list of the major references to subjects in the BASIC Reference Manual, the 
BASIC User's Guide, and the system-specific manuals. The index uses the following conventions: 

Example Explanation 

1— 8t A page number followed by a t indicates a table. 

4-36f A page number followed by an f indicates a figure. 

Entries in the Master Index are also preceded by an acronym indicating which manual the page number 
refers to: 

Acronym Title 

LM BASIC Reference Manual 

UG BASIC User's Guide 

RSTS BASIC on RSTS/E Systems 

RSX BASIC on RSX Systems 

VMS BASIC on VAX I VMS Systems 

Where a subject references more than one manual, references to the BASIC Reference Manual appear 
first, the BASIC User's Guide second, and the system-specific manuals appear last in alphabetical order. 

For a more complete list of references, see the individual indexes in the back of each manual. 



SB 

w 

CD 



Q. 
O 
X 



Index 



This index provides a complete cross-reference to the information in this manual. In the index the 
following convention is used: 

Example Explanation 

12t A page number followed by a t indicates a table. 

For material not covered in this manual, see the Master Index in the back of the BASIC Reference 
Manual. The Master Index contains a list of the major references to information throughout the BASIC 
documentation set. 



Abbreviations 

debugger command, 382 

qualifier, 83 
%ABORT, 1 1 3 
ABS, 293 
ABS%, 294 
Absolute value 

ABS, 293 

ABS%, 294 

MAG, 331 
ACCESS clause, 241, 258 

APPEND, 241 

MODIFY, 173, 191, 241 

READ, 173, 191, 241 

SCRATCH, 173, 241 

WRITE, 241 
Accessing 

CDD record definitions, 263 

RECORD items, 264, 265 
ACTIVE clause, 249 
Allocating storage 

for arrays, 1 59 

for FILL items, 141t, 227, 268 

for RECORD structures, 264 

for VARIANT fields, 265 

with COMMON, 139, 142 

with MAP, 210 

with MAP DYNAMIC, 213 

with REMAP, 268 



ALLOW clause, 241 

MODIFY, 174, 192, 241 

NONE, 174, 192, 241 

READ, 174, 192, 241 

WRITE, 241 
Alphanumeric label, 2 

See also Labels 
ALTERNATE KEY clause, 240, 244 
Ampersand (&) 

as a continuation character, 4, 6, 7 

in DATA statements, 1 43 
AND, 38 



^NS 



. .. : — .~l DAcir c*-«-J^-J o/ 

i mn iiiiuii DrOiv. Dicmuciiu, u*~ 



ANSLSTANDARD qualifier, 84 
APPEND, 43 to 44 
Arc tangent, 296 
Arithmetic operators, 30, 30t 
Arrays, 27 to 29 

array elements, 27, 159 

assigning values to, 206, 217, 219, 221, 
225, 261 

bounds, 159, 217, 219, 221, 223, 225 

bounds checking, 84 

converting with CHANGE, 136 

creating with COMMON, 140 

creating with DECLARE, 145 

creating with DIM, 158 

creating with MAP, 210 

creating with MAT statements, 216, 219, 
221, 223, 225 

data type of, 1 58 

definition of, 27 



February 1 984 



lndex-1 



Arrays (Cont.) 

dimensions of, 28, 158 

dynamic, 158, 159, 160 

element zero, 28, 159, 218, 220, 222, 224, 
226, 228 

initialization of, 161, 217 

inversion of, 218 

matrix arithmetic, 217 

naming, 29 

redimensioning with MAT statements, 217, 
218,219,221,225 

size limits, 28 

static, 158, 159 

transposition of, 218 

virtual, 29, 147, 158, 159, 170 
ASCII 

character set, 1 

characters, 24, 36, 299 

conversion, 136, 295, 299 

function, 295 

stream files, 245 
ASSIGN, 45 

Assigning logical names, 45 
Assigning string data 

with LSET, 209 

with RSET, 274 
Assigning values 

to array elements, 206, 217, 219, 221, 225, 
261 

to lexical constants, 121 

with INPUT, 199 

with INPUT LINE, 202 

with LET debugger command, 393 

with LET statement, 206 

with LINPUT, 207 

with LSET, 209 

with MAT INPUT, 219 

with MAT LINPUT, 221 

with MAT READ, 225 

with READ, 261 

with RSET, 274 
Asterisk (*) 

in PRINT USING format field, 255 

with HELP, 69 
Asterisk-filled field 

in PRINT USING, 255 
ATN, 296 
AUDIT qualifier, 84 

B 

Backslash () 
in continued lines, 6 
in multi-statement lines, 5 



Backslash () (Cont.) 

in PRINT USING format field, 256 

statement separator, 5 
BASIC character set, 1 
BEL, 23 

Binary radix, 21 
Blank-if-zero field 

in PRINT USING, 255 
Block I/O files, 94 

finding records in, 174 

opening, 240 

retrieving records sequentially in, 191 

writing records to, 258 
Block statements 

ending, 162 

exiting, 164 
BLOCKSIZE clause, 243 
Bounds, 27 

default for implicit arrays, 159, 217, 219, 
221, 223, 225 

maximum, 28 
BOUNDS_CHECK qualifier, 84 
BREAK debugger command, 383 to 384 
BRLRES command, 46 to 47 

BUILD default, 48 
BRLRES qualifier, 90 
BS, 23 
Buckets 

BUCKETSIZE clause, 244 

locking, 174, 192 

unlocking, 174, 182, 192 
BUCKETSIZE clause, 244 
BUFFER clause, 243 
BUFSIZ, 297 
BUILD, 48 

BASIC-PLUS-2 qualifiers, 90t 
BY clauses 

BY DESC, 131, 168, 185, 282 

BYREF, 131, 168, 185, 282 

BY VALUE, 131, 168 
BYTE data type, 1 1 
BYTE qualifier, 84, 90 



C formatting character 

in PRINT USING, 256 
CALL, 129 to 133 

as a debugger breakpoint, 383 

with SUB, 281 
Calling subprograms, 129, 281 
Caret () 

in PRINT USING format field, 255 
CASE clause, 276 
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CASE ELSE clause, 277 

CCPOS, 298 

CD 

in PRINT USING format field, 255 
CDD 
accessing definitions in, 263 

including definitions from, 7, 84, 88, 119 
Centered field 

in PRINT USING, 256 
CHAIN qualifier, 90, 134 
CHAIN statement, 134 to 135 
CHANGE, 136 to 137 

with NOSETUP, 87 
CHANGES clause, 244 
CHARACTER data type, 23 
Character position 

CCPOS, 298 

of substring, 322, 345 
Character sets 

ASCII, 10 

BASIC, 10 

translating with XLATE, 379 
Characters 

ASCII, 24, 36, 295, 299 

data type suffix, 1 3 

format in PRINT USING, 255 to 257 

lowercase, 58, 64, 66, 256 

nonprinting, 23 

processing of, 10 

uppercase, 58, 64, 66, 256 

wildcard, 69 
CHR$, 18, 299 
Clauses 

ACCESS, 173, 191, 241, 258 

ACTIVE, 249 

ALLOW, 174, 192, 241 

ALTERNATE KEY, 240, 244 

BLOCKSIZE, 243 

BUCKETSIZE, 244 

BUFFER, 243 

BY, 131, 168, 185, 282 

CASE, 276 

CHANGES, 244 

CLUSTERSIZE, 246 

CONNECT, 245, 246 

CONTIGUOUS, 242, 244, 245 

COUNT, 258, 289 

DEFAULTNAME, 240, 243 

DUPLICATES, 244, 259 

ELSE, 197 

END IF, 197 

EXTENDS1ZE, 243, 245, 246 

FILESIZE, 242 

FOR INPUT, 240 



Clauses (Cont.) 

FOR OUTPUT, 240 
GROUP, 264 
KEY, 172, 190, 271 

MAT, Z IZ, ZtJ 

MODE, 246 

NOREWIND, 243, 245, 247 

NOSPAN, 243 

ORGANIZATION, 240 

OTHERWISE, 236, 237 

PRIMARY KEY, 240, 244, 247 

RECORD, 172, 190, 258, 259 

RECORDSIZE, 212, 242, 258 

RECORDTYPE, 241 

REGARDLESS, 174, 192 

RFA, 172, 190 

STEP, 179 

TEMPORARY, 242 

THEN, 197 

UNLOCK EXPLICIT, 173, 175, 191, 245 

UNTIL, 180 

USEROPEN, 240, 243 

VARIANT, 264 

WHILE, 180 

WINDOWSIZE, 242 
CLOSE, 138 
Closing fiies, 138 

with END, 162 
CLUSTER qualifier, 90 
CLUSTERSIZE clause, 246 
CMD file, 48 
Colon (:) 

in labels, 2 
Comma (,) 

ill L/nin, i^tt 

in DELETE command, 54 

in INPUT, 199 

in INPUT LINE, 202 

in LINPUT, 207 

in LIST, 75 

in MAT PRINT, 224 

in PRINT, 251 

in PRINT USING format field, 255 
$ command, 49 to 50 
Command qualifiers, 83 to 94 

BASIC-PLUS-2, 90t 

VAX-1 1 BASIC, 84t 
Comment 

field, 8, 267 

in DATA statements, 9, 143 

processing of, 10 

REM, 9, 267 

transferring control to, 8 
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COMMON, 139 to 142 

size, 141 

with FIELD, 170 
Common Data Dictionary, 7 

See also CDD 

^/^k jnn/ ~tr\n 

Comparing 

numeric strings, 300 

strings, 36 
Comparisons 

EQ, 173, 191 

GE, 173, 191 

GT, 173, 191 
Compilation 

conditional, 117, 128 

control of, 7, 108 

control of listing, 114, 122, 123, 124, 125, 
126, 127 

controlling with OPTION, 249 

including from CDD, 7, 84, 88, 119 

including source code, 7, 1 1 9 

terminating with %ABORT, 113 
Compilation qualifiers, 83 to 94 

BASIC-PLUS-2, 90t 

VAX-1 1 BASIC, 84t 
COMPILE, 51 to 52 

BASIC-PLUS-2 qualifiers, 90t 

DEBUG qualifier, 381 

VAX-1 1 BASIC qualifiers, 84t 
Compiler directives, 7 
Components, 264 
CON, 217 
Concatenation 

of COMMON areas, 141 

string, 5, 30, 34 
Conditional branching 

with IF, 197 

with ON-GOSUB, 236 

with ON-GOTO, 237 

with SELECT, 276 
Conditional compilation, 7 

%VARIANT, 128 

with %IF, 117 
Conditional expressions, 34 to 40 

definition of, 34 

in %LET, 121 

in FOR, 1 80 

in IF, 197 

in UNLESS, 286 

in UNTIL, 288 

in WHILE, 292 
Conditional loops, 1 79, 288, 292 
CONNECT clause, 245, 246 



Constants, 1 4 to 24 

declaring, 146 

default data type, 1 5 

definition of, 14 

external, 166 

floating-point, 15 

integer, 17 

lexical, 117, 121 

named, 19 to 21 

numeric, 1 5 to 1 8 

packed decimal, 17 

predefined, 23 to 24 

string, 1 8 to 1 9 

types of, 14 
CONTIGUOUS clause, 242, 244, 245 
Continuation characters 

ampersand, 6 

backslash, 6 
CONTINUE command, 53 

with RUN, 103 
CONTINUE debugger command, 385 
Continued 

lines, 5 

statements, 4, 5 

string literals, 5 
Conversion 

of array to string variable, 1 36 

of string variable to array, 1 36 
Conversion functions 

CVT$%, 304 

CVT$F, 304 

CVT%$, 304 

CVTF$, 304 

DECIMAL, 307 

INTEGER, 325 

NUM$, 339 

NUM1$, 340 

RAD$, 351 

REAL, 354 

STR$, 365 

VAL, 377 

VAL%, 378 

XLATE, 379 
Copying BASIC source text, 7, 1 19 
CORE debugger command, 386 
COS, 301 
Cosine, 301 
COUNT clause 

with fixed-length records, 258, 289 

with variable-length records, 258, 289 
CPU time, 373 
CR, 24 



lndex-4 



February 1984 



Creating 

arrays, 140, 145, 158, 159, 210, 216, 219, 
221, 223, 225 

object modules, 51, 87, 93 

output iisting, 86, 92 

strings, 361, 366 
Credit-debit field 

in PRINT USING, 255 
%CROSS, 114 
Cross-reference table 

%CROSS, 114 

CROSS-REFERENCE qualifier, 84, 90 

%NOCROSS, 1 23 
CROSS-REFERENCE qualifier, 84, 90 
CTRL/C 

resuming after, 302 

trapping, 302, 352 

with RECOUNT function, 355 

with RESUME, 272 
CTRL/Z, 68 

editing command, 63 

with INPUT, 201 

with INPUT LINE, 203 

with LIN PUT, 208 
CTRLC, 302 

See also RCTRLC 
Cursor position 

CCPOS, 298 

TAB, 371 
CVT$$, 303 

See also EDITS 
CVTxx 

CVT$%, 304 

CVT$F, 304 

CVT%$, 304 

CVTF$, 304 

with FIELD, 1 69 



DATA, 143 to 144 

See also READ 

comment fields in, 9 

in DEF functions, 151 

in DEF* functions, 155 

in multi-statement lines, 7 

with MAT READ, 225 

with READ, 261 

with RESTORE, 271 
Datatypes, 10 to 14 

BYTE, 1 1 

CHARACTER, 23 

DECIMAL, 1 1 

decimal overflow checking, 87, 249 



Data types (Cont.) 

defining with RECORD, 263 

DOUBLE, 1 1 

GFLOAT, 1 1 

HFLOAT, 11 

in LET, 206 

in logical expressions, 37 

in numeric expressions, 31 

INTEGER, 1 1 

integer overflow checking, 87, 249 

keywords, 11, 12 

LONG, 1 1 

numeric literal notation, 21 

precision, 12 

precision in PRINT, 252 

precision in PRINT USING, 254 

promotion rules, 31 to 34 

range, 12 

REAL, 1 1 

results for DECIMAL data, 33t 

results for GFLOAT and HFLOAT, 32t 

results in expressions, 32t 

RFA, 12 

setting defaults with OPTION, 249 

SINGLE, 11 

size, 12 

storage of, 11, 12 

STRING, 11 

suffix characters, 1 3 

WORD, 1 1 
Data typing 

explicit, 13, 14 

implicit, 13 

with declarative statements, 14 

with suffix characters, 1 3 
Data-type defaults, 13, 14 

BYTE qualifier, 84, 90 

constants, 15 

DECIMAL-SIZE qualifier, 84 

DOUBLE qualifier, 85, 91 

GFLOAT qualifier, 86 

HFLOAT qualifier, 86 

LONG qualifier, 87, 92 

SINGLE qualifier, 88, 94 

TYPE-DEFAULT qualifier, 89, 94 

WORD qualifier, 89, 94 
Data-type functions 
DECIMAL, 307 
INTEGER, 325 
REAL, 354 
Data-type keywords, 1 1 
Date and time functions 
DATE$, 306 
TIME, 373 
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Date and time functions (Cont.) 

TIME$, 375 
DATES, 306 
Debit-credit field 

in PRINT USING, 255 
DEBUG qualifier, 84, 91 

with COMPILE, 381 

with RUN, 103, 279, 381 
Debugger 

BASIC-PLUS-2 commands, 381 to 405 

command abbreviations, 382 

effect on task size, 382 

prompt, 381 
Debugging 

changing variable values, 393 

DEBUG qualifier, 84, 91 

disabling of TRACE, 405 

disabling program breakpoints, 384, 403 

displaying program values, 395 

redirecting I/O operations, 397 

resuming execution, 385 

setting program breakpoints, 383 

TRACEBACK qualifier, 88 

tracing statement execution, 402 

with debugger commands, 103, 279 
DECIMAL data type, 1 1 

constants, 1 7 

format of, 1 3 

overflow checking, 87, 249 

promotion rules, 32 

rounding, 87, 249 

storage of, 1 1 
DECIMAL function, 307 
Decimal radix, 21 
DECIMAL_SIZE qualifier, 84 
Declarative statements 

COMMON, 140 

DECLARE, 145 

EXTERNAL, 166 

MAP, 210 
DECLARE, 145 to 148 

CONSTANT, 20, 24, 146, 147 

FUNCTION, 146, 147 
Declaring 

constants, 20, 146 

DEF functions, 146, 149 

DEF* functions, 153 

external constants, 1 66 

external subprograms, 1 85 

external subroutines, 166 

external variables, 166 

RECORD structures, 264 

variables, 145 
Declining features, 85, 91 



DEF, 149 to 152 

as a debugger breakpoint, 383 

ending, 162 

error handling in, 151, 163, 233, 234, 272 

exiting, 164 

multi-line, 150 

parameters, 150, 151 

recursion in, 151 

transferring control into, 151, 236, 237 

with INPUT, 199 

with INPUT LINE, 202 

with LINPUT, 207 

with NOSETUP, 87 

with READ, 261 
DEF*, 153 to 156 

error handling in, 155, 163 

multi-line, 154 

parameters, 154, 155 

recursion in, 155 

transferring control into, 155 
DEFAULTNAME clause, 240, 243 
Defaults 

BRLRES, 46 

BUCKETSIZE clause, 244 

BUILD, 48 

CLUSTERSIZE clause, 246 

COMMON name, 140 

COMPILE, 51 

constants, 15 

datatype, 13, 14, 249 

DEFAULTNAME clause, 243 

displaying, 109 

DSKLIB, 55 

EDIT, 57 

error handling, 233 

file name, 79, 82, 95, 97, 102, 104, 111, 

134, 240 
floating-point constants, 15 
implicitly declared variables, 26, 27 
integer constants, 17 
LIBRARY, 73 

listing file, 51, 84, 86, 90, 92 
LOAD, 77 

numeric constants, 1 5 
object module name, 51, 87, 93 
ODLRMS, 80 
overriding with BUILD, 48 
overriding with COMPILE, 51 
overriding with RUN, 102 
parameter passing mechanisms, 132t, 133t, 

168, 185, 282 
radix, 21 

RECORDSIZE clause, 242 
RESEQUENCE, 98 



lndex-6 



February 1984 



Defaults (Cont.) 
RMSRES, 100 
SCALE, 105 
scale factor, 249 
SEQUENCE, 107 
SET, 108 

setting with BRLRES, 46 
setting with DSKLIB, 55 
setting with LIBRARY, 73 
setting with ODLRMS, 80 
setting with OPTION, 248 
setting with RMSRES, 100 
SHOW, 109 

WINDOWSIZE clause, 242 
DEFINE editing command, 61 
Defining 
COMMON storage, 1 39 
data structures, 263 
labels, 2 

MAP DYNAMIC storage, 213 
MAP storage, 210 
DEL, 24 

DELETE command, 54 
DELETE statement, 157 
with UNLOCK, 287 
Deleting 
files, 111, 205, 242 
program lines, 54 
records, 157, 275 
Delimiter 
EDIT, 57 
in DATA, 144 
string literal, 18 

SUBSTITUTE editing command, 66 
Descriptors, 131, 168, 185, 282 
DET, 308 
Determinant, 308 
DIF$, 309 
DIM, 158 to 161 
executable, 159, 160 
nonvirtual, nonexecutable, 159 
used with MAT statements, 217, 218, 219, 

221, 223 
virtual, 159 
with NOSETUP, 87 
DIMENSION, 158 to 161 

See also DIM 
Dimensions 

of arrays, 28, 1 58 
Disk-resident libraries 
overriding defaults, 91 
setting defaults, 55 
Displaying 
defaults, 109 



Displaying (Cont.) 

program lines, 75 t 
Documentation 

on-line, 69 

*-.r^n*"yr*r* R t/\ 1fl 
iji vjgi ai 1 1, \J \.\J i *~" 

Dollar sign ($) 

in DECLARE, 145, 146 

in DEF names, 149, 150 

in DEF* names, 153, 154 

in FUNCTION names, 184 

in MAP DYNAMIC variables, 213 

in PRINT USING format field, 255 

in SUB names, 281 

in variable names, 25, 26 

suffix character, 1 3 

DOUBLE data type, 11 

DOUBLE qualifier, 85, 91 

DSKLIB command, 55 to 56 
BUILD default, 48 

DSKLIB qualifier, 91 

DUMP qualifier, 91 

DUPLICATES clause, 244, 259 

Dynamic 
arrays, 158, 159, 160 
mapping, 169, 213, 268 
storage, 213, 268, 269 



E formatting character 

in PRINT USING format field, 256 
E mathematical constant, 316 
E notation, 16 

field in PRINT USING, 255 

in nnmarlr litorpl nr^t^tion 91 
111 IILOHV.I l^ ll LV- I CI i i i >_/ *.\* iivn; £- ■ 

in PRINT USING format field, 256 

numbers in, 16t 

with PRINT, 252 

with STR$, 365 
ECHO, 310 

See also NOECHO 
EDIT, 57 to 60 
EDIT$, 311 

values, 31 1t 
Editing 

program lines, 57 

strings, 311, 376 

with a text editor, 58 

with editing commands, 58 
Editing commands, 60t 

DEFINE, 61 

EXECUTE, 62 

EXIT, 63 

FIND, 64 
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Editing commands (Cont.) 

INSERT, 65 

SUBSTITUTE, 66 
ELSE clause, 197 
END, 162 to 163 

DEF, 150, 154, 162 

FUNCTION, 162, 184 

GROUP, 162 

IF, 162, 197 

RECORD, 162 

SELECT, 162, 277 

SUB, 162, 281 

VARIANT, 162 
Ending 

multi-line DEF, 150, 162 

multi-line DEF*, 1 54 

programs, 162 

statement blocks, 1 62 

subprograms, 162, 184, 281 
EQ, 173, 191 
Equivalence name, 45 
EQV, 38 

ERL debugger command, 387 
ERL function, 312 

with labels, 2 

with NOLINE qualifier, 86, 92 

with RESEQUENCE, 99 
ERN debugger command, 388 
ERN$, 313 

ERR debugger command, 389 
ERR function, 314 
Error 

number, 314 

text, 315 
Error handling 

disabling, 235 

ERL, 312 

ERN$, 313 

ERR, 314 

ERT$, 315 

in DEF functions, 151, 163, 233, 234 

in DEF* functions, 155, 163 

in FOR-NEXT loops, 272 

in subprograms, 163, 164, 185, 233 

in UNTIL loops, 272 

in WHILE loops, 272 

ON ERROR GO BACK, 233 

ON ERROR GOTO, 234 

ON ERROR GOTO 0, 235 

recursion in, 234 

RESUME, 272 
Error handling functions 

CTRLC, 302 

ERL, 312 



Error handling functions (Cont.) 

ERN$, 313 

ERR, 314 

ERT$, 315 

RCTRLC, 352 
ERT$, 315 
ESC, 24 
Evaluation 

of expressions, 40 to 42 

of logical expressions, 38 to 40 

of numeric relational expressions, 35 

of operators, 40 

of SELECT statements, 277 

of string relational expressions, 36 
Exclamation point (!) 

in comment fields, 8 

in PRINT USING format field, 256 
Executable 

DIM, 159 

statements, 3 
EXECUTE editing command, 62 
Execution 

continuing, 53, 103, 385 

of multi-statement lines, 5 

of statements, 5 

of system commands, 49 

program, 102 

stopping, 53, 103, 279, 383, 400 

suspending, 278, 291 
EXIT command, 68 
EXIT debugger command, 390 
EXIT editing command, 63 
EXIT statement, 164 to 165 

DEF, 164 

FUNCTION, 164 

SUB, 164 
Exiting 

DEF functions, 164 

loops, 164 

statement blocks, 1 64 

subprograms, 164 
EXP, 316 
Explicit 

creation of arrays, 1 58 

data typing, 13, 14, 89, 94, 248 

declaration of variables, 27 

literal notation, 21 to 23 

loop iteration, 204 

record locking, 157, 173, 174, 175, 191, 
192, 245 
Exponential notation, 16, 252 

in PRINT USING, 255 

numbers in, 16t 

with PRINT, 252 
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Exponentiation, 316 
Expressions, 30 to 42 
conditional, 34 to 40 
conditional in %LET, 121 
definition of, 30 
evaluation of, 40 to 42 
lexical, 117, 121, 128 
logical, 37 to 40 
mixed-mode, 31 to 34 
numeric, 30 to 34 
numeric relational, 35 
operator precedence in, 40, 41 1 
parentheses in, 41 
relational, 35 to 37 
string, 34 

string relational, 36 
types of, 30 
EXTEND qualifier, 91 
Extended field 

in PRINT USING, 256 
EXTENDSIZE clause, 243, 245, 246 
EXTERNAL, 166 to 168 
BASIC-PLUS-2 parameter passing 

mechanisms, 133t 
CONSTANT, 20, 166 
FUNCTION, 166 
parameters, 167 
SUB, 166 
VAX-1 1 BASIC parameter passing 

mechanisms, 132t 
with NOSETUP, 87 
External 
constants, 20, 166 
functions, 166 
subroutines, 166 
variables, 26, 166 
Extracting substrings 
with LEFT$, 326 
with MID$, 335 
with RIGHT$, 356 
with SEG$, 358 



Features 

declining, 85, 91 
FF, 24 
FIELD, 169 
Fields 

asterisk-filled, 255 

blank-if-zero, 255 

centered, 256 

comment, 8 

credit or debit, 255 



Fields (Cont.) 
exponential, 255 
extended, 256 
floating dollar sign, 255 

rpni id it/! 

left-justified, 256 

one-character, 256 

right-justified, 256 

trailing minus sign, 255 

VARIANT, 264 

zero-fill, 255 
File attributes 

BLOCKSIZE clause, 243 

CLUSTERSIZE clause, 246 

CONTIGUOUS clause, 242 

EXTENDSIZE clause, 243 

FILESIZE clause, 242 

magnetic tape, 243 

MODE clause, 246 
File names 

BUILD default, 48 

CHAIN statement default, 1 34 

COMPILE default, 51 

LOAD default, 77 

NEW default, 79 

OLD default, 82 

OPEN default, 240 

RENAME default, 95 

REPLACE default, 97 

RUN default, 102 

SAVE default, 104 

UNSAVE default, 111 
File-related functions 

BUFSIZ, 297 

rrDnc too 

FSP$, 319 
FSS$, 320 
GETRFA, 321 
MAGTAPE, 332 
MAR, 334 
ONECHR, 341 
RECOUNT function, 355 
STATUS, 363 
Files 
ASCII stream, 245 
block I/O, 94, 174, 191, 240, 258 
closing, 138 
deleting, 111, 205, 242 
deleting records in, 157, 275 
finding buffer size, 297 
%INCLUDE, 98, 119, 120 
indexed, 92, 157, 174, 191, 240, 243, 244, 

258, 271, 290 
magnetic tape, 243, 271, 332 
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Files (Cont.) 
opening, 238 
relative, 93, 157, 173, 191, 240, 242, 244, 

258, 290 
renaming, 230 

rpcfprina rlafa 9 71 

RMS sequential stream, 245 

sequential, 93, 173, 191, 240, 242, 243, 
251, 258, 275, 289 

terminal-format, 199, 202, 207, 215, 219, 
221, 223, 232, 244, 251 

virtual, 94, 242, 271 
FILESIZE clause, 242 
FILL, 139, 210, 227, 268 
FILL items 

formats and storage, 1 41 1 

in COMMON, 139 

in MAP, 210 

in MOVE, 227 

in REMAP, 268 
FILL$, 139, 210, 227, 268 
FILL%, 139, 210, 227, 268 
FIND editing command, 64 
FIND statement, 171 to 176 

with PUT, 259 

with UNLOCK, 287 

with UPDATE, 289 
Finding 

records, 174 

string length, 327 

substrings, 322, 345 

virtual address, 328 
FIX, 317 

compared with INT, 324 
FLAG qualifier 

BP2COMPATIBILITY, 85 

DECLINING, 85, 91 
Floating dollar sign field 

in PRINT USING, 255 
Floating-point 

constants, 15 

data types, 1 1 

promotion rules, 31 

variables, 26 
FNEND, 177 

See also END 
FNEXIT, 178 

See also EXIT 
FOR clause 

INPUT, 240 

OUTPUT, 240 
FOR statement, 179 to 181 
FOR-NEXT loops, 179 to 181, 231 

conditional, 179 



FOR-NEXT loops (Cont.) 

error handling in, 272 

exiting, 164 

explicit iteration of, 204 

nested, 179 

transferring control into, 180, 195, 196, 236, 
237 

unconditional, 179 
Format 

characters in PRINT USING, 255 

E, 16, 252 

explicit literal notation, 21 

exponential, 16, 252 

for SET qualifiers, 83 

of comment field, 8 

of compiler directives, 7 

of data, 11 

of data in DATA statements, 144 

of DECIMAL data, 1 3 

of empty statements, 10 

of external constant name, 21 

of external variable names, 26 

of FILL items, 141t 

of floating-point constants, 15 

of implicitly declared variables, 26, 27 

of integer constants, 17 

of internal constant name, 19 

of internal variable names, 25 

of keywords, 3 

of labels, 2 

of line numbers, 1 

of logical expressions, 37 

of multi-line REM, 9, 267 

of multi-statement lines, 6, 7 

of numeric expressions, 30 

of packed decimal constants, 1 7 

of program lines, 1 to 8 

of relational expressions, 35 

of statements, 3 

of string constants, 18 

of subscripted variables, 28 

Radix-50, 351 
FORMATS, 318 
Formatting 

MAT PRINT output, 224 

numeric output, 255 to 256 

PRINT output, 251, 253 

storage with LSET, 209 

storage with RSET, 274 

string output, 256 to 257 

with FORMATS, 318 

with PRINT USING, 254 to 257 
FREE debugger command, 391 
FREE statement, 182 
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FSP$, 319 
FSS$, 320 
FUNCTION, 183 to 186 

BASIC-PLUS-2 parameter passing 
mechanisms, 1 33t 

parameters, 184 

VAX-1 1 BASIC parameter passing 
mechanisms, 132t 
Function codes 

MAGTAPE, 332t 
FUNCTIONEND, 187 

See also END 
FUNCTIONEXIT, 188 

See also EXIT 
Functions 

declaring, 146, 149, 153 

external, 166 

initialization of, 151, 155 

invocation of, 151, 155 

lexical, 89, 94, 1 17, 121, 128 

naming, 149, 153 

parameters, 150, 154 

user-defined, 149, 153 



GE, 173, 191 

GET, 189 to 194 
with PUT, 259 
with UNLOCK, 287 
with UPDATE, 289 

GETRFA, 321 

GFLOAT data type, 1 1 

GFLOAT qualifier, 86 

GOSUB, 195 
with RETURN, 273 

GOTO, 196 

GROUP clause, 264 

GT, 173, 191 



H 



Halting program execution, 53, 279, 383, 400 

HELP, 69 to 70 

Hexadecimal radix, 21 

HFLOAT data type, 1 1 

HFLOAT qualifier, 86 

HT, 23 

Hyphen (-) 

in DELETE command, 54 

in LIST command, 75 



! 



I/O 
characters transferred, 355 

„!„-:„„ £:!„,- no id 

deleting records, 157 
dynamic mapping, 268 
finding records, 173 
getting records, 191 
I/O BUFFER debugger command, 392 
locking records, 173, 174, 191, 192, 245 
matrix, 337, 338 
moving data, 227 
opening files, 238 

RECOUNT debugger command, 396 
retrieving records, 191 
STATUS debugger command, 398 
unlocking records, 182, 245, 287 
updating records, 289 
with CHAIN, 135 
writing records, 258 
I/O BUFFER debugger command, 392 
%IDENT, 115 to 116 
IDENTIFY, 71 

Identifying module version, 115 
Identity matrix, 217 
IDN, 217 
%IF-%THEN-%ELSE-%END %IF, 117 to 118 

with RESEQUENCE, 98 
IF-THEN-ELSE, 197 to 198 
labels in, 2 
multi-line format, 6 
Immediate mode, 53, 103 
IMP, 38 
implicit, 
continuation of lines, 6 
creation of arrays, 159, 217, 219, 221, 223, 

225 
data typing, 13, 147 
declaration of variables, 26 to 27 
%INCLUDE, 119 to 120 
with RESEQUENCE, 98 
IND qualifier, 92 
Indexed files 
ALTERNATE KEY clause, 244 
BUCKETSIZE clause, 244 
CHANGES clause, 244 
deleting records in, 157 
DUPLICATES clause, 244 
finding records in, 1 74 
IND qualifier, 92 
MAP clause, 243 
opening, 240 
PRIMARY KEY clause, 244 
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Indexed files (Cont.) 

restoring data in, 271 

retrieving records sequentially in, 191 

segmented keys in, 244 

updating, 290 

writing records to, 258 
Initialization 

in subprograms, 1 85, 282 

of arrays, 217 

of DEF functions, 151 

of DEF* functions, 1 55 

of dynamic arrays, 161 

of variables, 29, 147 

of variables in COMMON, 142 

of variables in MAP, 212 

of virtual arrays, 160 
INPUT, 199 to 201 
INPUT LINE, 202 to 203 
Inputting data 

ONECHR, 341 

with INPUT, 199 

with INPUT LINE, 202 

with LIN PUT, 207 
INQUIRE, 72 

See also HELP 
INSERT editing command, 65 
Instance, 264 

RECORD, 264 
INSTR, 322 to 323 

See also POS 
INT, 324 
Integer 

constants, 17 

datatypes, 11 

overflow checking, 87, 249 

promotion rules, 31 

suffix character, 1 3 

variables, 27 
INTEGER data type, 1 1 
INTEGER function, 325 
INV, 218 

Inverting arrays, 218, 308 
ITERATE, 204 
Iteration 
of FOR loops, 1 80 
of loops, 204 
of UNTIL loops, 288 
of WHILE loops, 292 



Justifying strings 
with LSET, 209 
with RSET, 274 



KEY clauses 

ALTERNATE, 240, 244 

in FIND, 172 

in GET, 190 

in RESTORE, 271 

PRIMARY, 240, 244, 247 

segmented keys, 244 
Keywords 

data-type, 11 

definition of, 3 

function of, 3 

in RECORD, 264 

restrictions, 3 

spacing requirements, 4, 4t 
KILL, 205 



L formatting character 

in PRINT USING, 256 
Labels 

defining, 2 

format of, 2 

function of, 2 

referencing, 2 

transferring control to, 195, 196, 236, 237 

with ITERATE, 204 
LEFT$, 326 

See also SEG$ 
Left-justification 

PRINT USING format field, 256 

with LSET, 209 
LEN, 327 
Length 

label, 2 

of STRING data, 12 

variable names, 25 
%LET, 121 

LET debugger command, 393 to 394 
LET statement, 206 
Letters 

lowercase, 10, 58, 64, 66, 256 

uppercase, 10, 58, 64, 66, 256 
Lexical 

constants, 117, 121 

expressions, 117, 121, 128 

functions, 89, 94, 117, 121, 128 

operators, 117, 121 

order, 8 
LF, 24 
Libraries 

clustering, 90 
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Libraries (Cont.) 
disk-resident, 55 
memory-resident, 46, 73 
RMS, 100, 101t 

setting defaults with BRLRES, 46 
setting defaults with DSKLIB, 55 
setting defaults with LIBRARY, 73 
LIBRARY command, 73 to 74 

BUILD default, 48 
LIBRARY qualifier, 92 
Line numbers 
automatic sequencing, 107 
format of, 1 
function of, 2 

in %INCLUDE file, 98, 119 
in object modules, 86, 92 
in RESEQUENCE, 98 
range of, 1 
LINE qualifier, 86, 92, 134 
with debugger commands, 387, 388 
with ERL, 312 
Line terminator, 1,7,10 
with DATA statements, 1 43 
with INPUT, 200 
with INPUT LINE, 203 
with LINPUT, 208 
Lines 
continued, 5 
deleting, 54 
displaying, 75 
editing, 57 
elements of, 1 
format of, 1 to 8 
length of, 1 

muiti-statement, 5 to 7 
order of, 8, 98 
single-statement, 4 
terminating, 1, 7, 10 
LINPUT, 207 to 208 
%LIST, 122 

LIST command, 75 to 76 
LIST qualifier, 86, 92 
Listing file 
control of, 7, 88, 114, 122, 123, 124, 125 
creating, 86, 92 
%CROSS, 114 

CROSS-REFERENCE qualifier, 84, 90 
defaults, 51, 84, 86, 90, 92 
included code, 119 
%LIST, 122 
%NOCROSS, 123 
%NOLIST, 124 
%PAGE, 125 
%SBTTL, 126 



Listing file (Cont.) 
setting page size, 93 
setting width, 94 
subtitle, 126 

o/TIT! C 117 

/Dill t-t-f I £./ 

title, 127 

version identification, 1 1 5 
LISTNH, 75 

See also LIST 
Literal 

explicit notation, 21 

numeric, 15 

string, 5, 10, 18, 37, 255, 257 
LOAD, 77 

with RUN, 103 

with SCRATCH, 106 
LOC, 328 
Local copy, 1 3 1 
Locating records 

by KEY, 172, 174, 190, 192 

by RECORD number, 172, 190 

by RFA, 172, 174, 190, 192 

sequentially, 172, 173, 190, 191 

with FIND, 171 

with GET, 189 
LOCK, 78 

See also SET 
Lock checking 

REGARDLESS clause, 174, 192 
Locking records, 245 

with FIND, 173, 174, 175 

with GET, 191, 192 
LOG, 329 
LOG10, 330 
Logarithms 

common, 330 

natural, 329 
Logical expressions, 37 to 40 

compared with relational, 40 

data types in, 37 

definition of, 34 

evaluation of, 38 to 40 

format of, 37 

logical operators, 38t 

truth tables, 38t 

truth tests, 38 
Logical name, 45 
Logical operators, 38t 
LONG data type, 1 1 
LONG qualifier, 87, 92 
Loops 

as debugger breakpoints, 383 

conditional, 179 

exiting, 164 
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Loops (Cont.) 

FOR-NEXT, 179 

iteration of, 180, 204, 288, 292 

nested FOR-NEXT, 179 

unconditional, 179 

UNTIL, 288 

WHILE, 292 
Lowercase letters 

in EDIT, 58 

in FIND editing command, 64 

in PRINT USING, 256 

in SUBSTITUTE editing command, 66 

processing of, 10 
LSET, 209 



M 



MACHINE_CODE qualifier, 87 
MACRO qualifier, 92 
MAG, 331 
Magnetic tape files 

BLOCKSIZE clause, 243 

MAGTAPE, 332 

NOREWIND clause, 243 

RESTORE, 271 
MAGTAPE, 332 to 333 

function codes, 332t 

performing functions in VAX-1 1 BASIC, 
333t 
MAP clause, 212, 243 
MAP DYNAMIC, 213 to 214 

with REMAP, 268, 269 
MAP qualifier, 93 
MAP statement, 210 to 212 

FILL item formats and storage, 141t 

with FIELD, 170 

with MAP DYNAMIC, 214 

with REMAP, 268 
Mapping 

dynamic, 169, 213, 268 

static, 210 
MAR, 334 
MAR%, 334 
MARGIN, 215 

See also NOMARGIN 

with PRINT, 251 
Margin 

width, 215, 232, 251, 334 
MAT, 216 to 218 

with DET, 308 

with FIELD, 170 

with NOSETUP, 87 
MAT INPUT, 219 to 220 

with NOSETUP, 87 



MAT LINPUT, 221 to 222 

with NOSETUP, 87 
MAT PRINT, 223 to 224 

with NOSETUP, 87 
MAT READ, 225 to 226 

with NOSETUP, 87 
Matrix, 28 

identity, 217 
Matrix functions 
DET, 308 
NUM, 337 
NUM2, 338 
Matrix operations 
arithmetic, 217 

assigning values, 219, 221, 225 
I/O, 337, 338 
inversion, 218, 308 
printing, 223 

redimensioning, 219, 221, 223, 225 
scalar multiplication, 218 
transposition, 218 
Memory 
allocation, 386, 391, 392, 401 
clearing with SCRATCH, 106 
DUMP qualifier, 91 
effect of debugger on, 382 
Memory-resident libraries 
clustering, 90 
overriding defaults, 90, 92 
setting defaults with BRLRES, 46 
setting defaults with LIBRARY, 73 
Merging programs, 43 
MID$, 335 

See also SEG$ 
Minus sign (-) 
in numeric literal notation, 21 
in PRINT USING format field, 255 
Mixed-mode expressions, 31 to 34 
MODE clause, 246 
Modifiable parameters, 131 
Modifiers 
FOR, 179 
IF, 197, 198 
UNLESS, 286 
UNTIL, 288 
WHILE, 292 
MOVE, 227 to 229 
FILL item formats and storage, 1 41 1 
with FIELD, 170 
with NOSETUP, 87 
Multi-line 

DEF, 149, 150 
DEF*, 153, 154 
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Multi-statement lines, 5 to 7 
backslash in, 5 
branching to, 6 
execution of, 5 



lornidi ui, u, 



implicit continuation, 6 
transferring control to, 5 

N 

NAME AS, 230 

Named constants, 19 to 21 

changing, 19 

external, 20, 166 

internal, 19, 146 
Naming 

arrays, 29 

COMMON areas, 140 

constants, 15, 19, 146 

DEF functions, 149 

DEF* functions, 153 

external constants, 20, 1 66 

external functions, 1 66 

external subroutines, 166 

external variables, 26, 1 66 

FUNCTION subprograms, 184 

functions, 146 

internal constants, 19, 146 

internal variables, 25 

lexical constants, 121 

MAP areas, 210 

programs, 79, 95 

SUB subprograms, 281 

subprograms, 130 

vanauies, > 45 
Nesting 

FOR-NEXT ioops, 179 

IF, 197 

SELECT, 277 
NEW, 79 
NEXT, 231 

with FOR, 1 80 

with UNTIL, 288 

with WHILE, 292 
%NOCROSS, 123 
NOECHO, 336 

See also ECHO 
NOLINE qualifier, 279 
%NOLIST, 124 
NOMARGIN, 232 

See also MARGIN 
Nonexecutable DIM, 1 59 
Nonexecutable statements, 3, 8 
COMMON, 141 



Nonexecutable statements (Cont.) 
DATA, 143 
DECLARE, 147 
DIM, 159 
EXTERNAL, 168 
MAP, 211 

MAP DYNAMIC, 214 
REM, 267 
with UNLESS, 286 
Nonmodifiable parameters, 131 
Nonprinting characters 
processing of, 10 
using, 10 
Nonvirtual DIM, 159 
NOREVViND clause, 243, 245, 247 
NOSPAN clause, 243 
NOT, 38 

evaluation of, 41 
Notation 

E, 16, 16t, 252, 255, 256 
explicit literal, 21 to 23 
exponential, 16, 252 
NUL, 10, 18 
NUL$, 217 
NUM, 337 
after MAT INPUT, 220 
after MAT LIN PUT, 221 
after MAT READ, 225 
NUM$, 339 
NUM1$, 340 

compared with STR$, 365 
NUM2, 338 
after MAT INPUT, 220 
after MAT LIN PUT, 222 
after MAT READ, 226 
Numbers 

random, 260, 357 
sign of, 359 
Numbers in E notation, 16t 
Numeric constants, 15 to 18 
Numeric conversion, 136 
Numeric expressions, 30 to 34 
format of, 30 
promotion rules, 31 to 34 
result data types, 32t 
results for DECIMAL data, 33t 
results for GFLOAT and HFLOAT, 32t 
Numeric functions, 304 
ABS, 293 
ABS%, 294 
DECIMAL, 307 
FIX, 317 
INT, 324 
LOG, 329 
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Numeric functions (Cont.) 

LOG10, 330 

MAC, 331 

RND, 357 

SGN, 359 

SQR, 362 

SWAP%, 368 
Numeric literal notation, 21 to 23 
Numeric operator precedence, 41 1 
Numeric precision 

with PRINT, 252 

with PRINT USING, 254 
Numeric relational expressions 

evaluation of, 35 

operators, 35t, 35 
Numeric string functions 

CHR$, 299 

COMP%, 300 

DECIMAL, 307 

DIF$, 309 

FORMATS, 318 

INTEGER, 325 

NUM$, 339 

NUM1$, 340 

PLACES, 342 

PROD$, 347 

QUO$, 349 

REAL, 354 

STR$, 365 

SUM$, 367 

VAL, 377 

VAL%, 378 
Numeric strings 
comparing, 300 

precision, 309, 342, 347, 349, 367 
rounding, 342, 347, 349 
rounding and truncation values, 344t 
truncating, 342, 347, 349 



Object module 

creating, 51, 87, 93 

default name, 51, 87, 93 

line numbers in, 86, 92 

loading, 77 

version identification, 115 
OBJECT qualifier, 87, 93 
Object Time System (OTS), 55 
Octal radix, 21 
ODLfile, 48, 81t 

overriding defaults, 93 

RMS libraries, 101t 

setting defaults, 80 



ODLRMS command, 80 to 81 

BUILD default, 48 
ODLRMS qualifier, 93 
OLD, 82 

with RUN, 103 
ON ERROR GO BACK, 233 
with END, 162 
with NOSETUP, 87 
ON ERROR GOTO, 234 
with END, 162 
with NOSETUP, 87 
ON ERROR GOTO 0, 233, 235 
with END, 162 
with NOSETUP, 87 
ON-GOSUB-OTHERWISE, 236 

with RETURN, 273 
ON-GOTO-OTHERWISE, 237 
On-line documentation, 69 
One-character 
input, 341 

PRINT USING format field, 256 
ONECHR, 341 
OPEN, 238 to 247 

with STATUS, 363 
Opening files, 238 to 247 

with USEROPEN clause, 243 
Operator precedence, 30, 40, 41 1 
Operators 
arithmetic, 30, 30t 
evaluation of, 40 
lexical, 117, 121 
logical, 38t 

numeric operator precedence, 41 1 
numeric relational, 35t 
precedence of, 30, 40, 41 1 
string relational, 37t 
OPTION, 248 to 250 
OR, 38 
Order 

lexical, 8 
ORGANIZATION clause, 240 
OTHERWISE clause, 236, 237 
Output 
formatting with FORMATS, 318 
formatting with PRINT USING, 254 to 256 
Output listing 
creating, 86, 92 

cross-reference table, 84, 90, 114, 123 
default, 51, 84, 90 
%LIST, 122 
%NOLIST, 124 
%PAGE, 125 
%SBTTL, 126 
setting page size, 93 
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Output listing (Cont.) 
setting width, 94 
%T!TLE, 127 

Overflow checking, 87, 249 

OVERFLOW qualifier 
DECIMAL, 87 
INTEGER, 87 

Overlay description file, 80 
See also ODL file 

Overlaying 
COMMON areas, 142 
MAP areas, 21 1 

Overriding defaults 
with BRLRES qualifier, 90 
with BUILD, 48 
with COMPILE, 51 
with DECLARE, 145, 148 
with DSKL1B qualifier, 91 
with EXTERNAL, 166 
with LIBRARY qualifier, 92 
with ODLRMS qualifier, 93 
with RMSRES qualifier, 93 
with RUN, 102 



Packed decimal, 11 

See also DECIMAL data type 
Padding 

in string relational expressions, 36 

in virtual arrays, 160 
%PAGE, 125 
PAGE_SIZE qualifier, 93 
Parameter passing mechanisms 

BASiC-PLUS-2, 133t 

CALL, 131 

DEF, 151 

DEF*, 155 

EXTERNAL, 168 

FUNCTION, 185 

SUB, 282 

VAX-11 BASIC, 132t 
Parameters 

CALL, 131 

DEF, 150, 151 

DEF*, 154, 155 

EXTERNAL, 167 

function, 150, 154 

FUNCTION subprograms, 184 

modifiable, 131 

nonmodifiable, 131 

SUB subprograms, 281 
Parentheses 

in array names, 27 



Parentheses (Cont.) 

in expressions, 30, 40 
Percent sign (%) 

in DATA statements, 17, 143 

:._ r^r/— I A r»r- t A r i A f 

ill uc^Lnr^c, 143, i to 

in DEF names, 150 

in DEF* names, 154 

in FUNCTION names, 184 

in MAP DYNAMIC variables, 213 

in PRINT USING format field, 255 

in SUB names, 281 

in variable names, 25, 26 

suffix character, 1 3 
Period (.) 

in PRINT USING format field, 255 

in variable names, 25 
PI, 24 
PLACES, 342 to 344 

rounding and truncation values, 344t 
Plus sign () 

in string concatenation, 34 
POS, 345 to 346 
Pound sign () 

debugger prompt, 381 

in PRINT USING format field, 255 
Precedence 

numeric operator, 41 1 

operator, 30, 40 
Precision 

in PRINT, 252 

in PRINT USING, 254 

NUM$, 339 

NUM1$, 340 

of data types, 1 2 

of numeric strings, 309, 342, 347, 349, 367 
Predefined constants, 23 to 24 

function of, 23 
PRIMARY KEY clause, 240, 244, 247 
PRINT debugger command, 395 
PRINT statement, 251 to 253 

with TAB, 371 
PRINT USING, 254 to 257 
Print zones 

in MAT PRINT, 224 

in PRINT, 251 
Printing 

to a terminal, 251 

to a terminal-format file, 251 
Processing 

INPUT data, 200 

INPUT LINE data, 203 

LINPUT data, 208 

multiple record streams, 245 

of comments, 10 
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Processing (Cont.) 

of lowercase letters, 1 

of nonprinting characters, 1 

of statements, 8 

of string constants, 18 

of string literals, 10 

of uppercase letters, 10 

records, 189, 258, 289 
PROD$, 347 to 348 

rounding and truncation values, 344t 
Program control statements 

END, 162 

EXIT, 164 

FOR, 1 79 

GOSUB, 195 

GOTO, 196 

IF, 197 

ITERATE, 204 

ON-GOSUB, 236 

ON-GOTO, 237 

RESUME, 272 

RETURN, 273 

SELECT, 276 

SLEEP, 278 

STOP, 279 

UNTIL, 288 

WAIT, 291 

WHILE, 292 
Program documentation, 8 to 10 
Program elements, 1 to 42 
Program execution 

continuing, 53, 103, 385 

initiating with RUN, 102 

stopping, 53, 103, 279, 383, 400 

suspending, 278 

waiting for input, 291 
Program input 

INPUT, 199 

INPUT LINE, 202 

LINPUT, 207 

waiting for, 291 
Program lines 

automatic sequencing, 107 

deleting, 54 

displaying, 75 
editing, 57 
elements of, 1 
format of, 1 to 8 

length of, 1 
numbering, 1 
order of, 8, 98 
resequencing, 98 
terminating, 1, 7, 10 



Programs 

compiling, 51 

continuing, 53, 103 

debugging, 84, 91, 103 

deleting, 111 

editing, 57 

ending, 162 

executing, 102 

halting, 53, 103, 279 

merging, 43 

naming, 79 

optimizing, 87 

renaming, 95 

saving, 97, 104 

stopping, 53, 103, 279 
Promotion rules 

datatype, 31 to 34 

DECIMAL, 32 

floating-point, 31 

integer, 31 
Prompt 

after STOP, 279 

debugger, 381 

INPUT, 199 

INPUT LINE, 202 

LINPUT, 207 

MAT INPUT, 219 

MAT LINPUT, 221 
PSECT, 139, 210 
PUT, 258 to 259 

Q 

Qualifiers, 83 to 94 
abbreviated form, 83 
ANSLSTANDARD, 84 
AUDIT, 84 

BASIC-PLUS-2 command, 90t 
BOUNDS_CHECK, 84 
BRLRES, 90 
BYTE, 84, 90 
CHAIN, 90, 134 
CLUSTER, 90 

CROSS_REFERENCE, 84, 90 
DEBUG, 84, 91, 103, 381 
DECIMAL_SIZE, 84 
DOUBLE, 85, 91 
DSKLIB, 91 
DUMP, 91 
EXTEND, 91 
FLAG, 85, 91 
GFLOAT, 86 
H FLOAT, 86 
IND, 92 
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Qualifiers (Cont.) 

LIBRARY, 92 

LINE, 86, 92, 134, 387, 388 

LIST 86 

LONG, 87, 92 

MACHINE_CODE, 87 

MACRO, 92 

MAP, 93 

NOLINE, 279 

OBJECT, 87, 93 

ODLRMS, 93 

OVERFLOW, 87 

PAGE_SIZE, 93 

REL, 93 

RMSRES, 93 

ROUND, 87 

SEQ, 93 

SETUP, 87 

SHOW, 88, 120 

SINGLE, 88, 94 

SYNTAX_CHECK, 88, 94 

TRACEBACK, 88 

TYPE_DEFAULT, 89, 94 

VARIANT, 89, 94, 128 

VAX-1 1 BASIC command, 84t 

VIR, 94 

WARNINGS, 89 

WIDTH, 94 

WORD, 89, 94 
QUO$, 349 to 350 

rounding and truncation values, 344t 
Quotation marks 

in string literals, 18 



R formatting character 

in PRINT USING, 256 
RAD$, 351 
Radix 

binary, 21 

decimal, 21 

hexadecimal, 21 

in explicit literal notation, 21 

octal, 21 
Radix-50, 351 
Random numbers, 260, 357 
RANDOMIZE, 260 

See also RND 
Range 

of data types, 1 2 

of subscripts, 28 
RCTRLC, 352 

See also CTRLC 



RCTRLO, 353 
READ, 261 to 262 
See also DATA 
with DATA, 143, 144 
with NOSETUP, 88 
REAL data type, 1 1 
REAL function, 354 
Receiving parameters 
FUNCTION subprograms, 184 
SUB subprograms, 281 
Record attributes 
MAP clause, 243 
RECORDSIZE clause, 242, 243 
RECORDTYPE clause, 241 
Record buffers 
DATA pointers, 271 
MAP DYNAMIC pointers, 214, 269 
moving data, 227 
REMAP pointers, 268, 269 
setting size, 243 
RECORD clause, 172, 190, 258, 259 
Record File Address, 12, 172, 190, 321 
Record Management Services, 80 

See also RMS 
Record pointers 
after FIND, 173, 174 
after GET, 191, 192 
after PUT, 259 
after UPDATE, 289 
REMAP, 269 
RESTORE, 271 
WINDOWSIZE clause, 242 
RECORD statement, 263 to 266 
Records 
deleting with DELETE, 157 
deleting with SCRATCH, 275 
finding RFA of, 172, 190 
locating randomly, 1 74 
locating sequentially, 1 73 
locating with FIND, 171 
locking, 173, 174, 191, 192, 245 
processing of, 245 
retrieving by KEY, 190, 192 
retrieving by RECORD number, 190 
retrieving by RFA, 190, 192 
retrieving randomly, 192 
retrieving sequentially, 190, 191 
retrieving with GET, 189 
size of, 258 

unlocking, 157, 174, 182, 192, 245, 287 
writing with PRINT, 251 
writing with PUT, 258 
writing with UPDATE, 289 
RECORDSIZE clause, 212, 242, 258 
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RECORDTYPE clause 

ANY, 241 

FORTRAN, 241 

LIST, 241 

NONE, 241 
RECOUNT debugger command, 396 
RECOUNT function, 355 

after GET, 192 

after INPUT, 200 

after INPUT LINE, 203 

after LIN PUT, 208 
Recursion 

in DEF functions, 151 

in DEF* functions, 155 

in error handlers, 234 

in subprograms, 132, 282 
Redimensioning arrays 

dynamic, 160 

with executable DIM, 1 59 

with MAT statements, 217, 218, 219, 221, 
225 
REDIRECT debugger command, 397 
Referencing labels, 2 
REGARDLESS clause 

with FIND, 174 

with GET, 1 92 
REL qualifier, 93 
Relational expressions, 35 to 37 

compared with logical, 40 

definition of, 34 

format of, 35 

in SELECT, 276, 277 

numeric, 35 

string, 36 

truth tests, 35, 36 
Relational operators 

numeric, 35t 

string, 37t 
Relative files 

BUCKETSIZE clause, 244 

deleting records in, 157 

finding records in, 173 

opening, 240 

record size in, 242 

REL qualifier, 93 

retrieving records sequentially in, 191 

updating, 290 

writing records to, 258 
REM, 267 

in multi-statement lines, 7 

multi-line format, 9, 267 

transferring control to, 9 
REMAP, 268 to 270 

FILL item formats and storage, 1 41 1 



REMAP (Cont.) 

with MAP DYNAMIC, 214 

with NOSETUP, 88 
RENAME, 95 to 96 
Renaming 

files, 230 

programs, 95 
REPLACE, 97 

with RENAME, 95 
RESEQUENCE, 98 to 99 
Reserved words, 3 
RESET, 271 

See also RESTORE 
RESTORE, 271 
Restoring 

data, 271 

files, 271 
Result data types 

for DECIMAL data, 33t 

GFLOAT and HFLOAT, 32t 

mixed-mode expressions, 32t 
RESUME, 272 

after CTRL /C, 272 

to INPUT, 200 

to INPUT LINE, 203 

to LINPUT, 208 

with CTRLC, 302 

with END, 162 

with ERL, 312 

with ERN$, 313 

with ERR, 314 

with labels, 2 

with NOLINE qualifier, 86, 92 

with NOSETUP, 88 
Retrieving records 

randomly by KEY, 190, 192 

randomly by RECORD number, 1 90 

randomly by RFA, 190, 192 

sequentially, 190, 191 

with GET, 189 
RETURN, 273 
RFA clause, 172, 190 
RFA data type 

allowable operations, 12 

storage of, 1 2 
RIGHTS, 356 

See also SEG$ 
Right-justification 

PRINT USING format field, 256 

with RSET, 274 
RMS 

files, 238 

libraries, 93, 100, 101t 

ODL files, 80, 81t 
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RMSRES command, 100 to 101 

BUILD default, 48 
RMSRES qualifier, 93 
RND, 357 

/- _ _!__ n A t<. ir\S~\k JU-7E 

:>ee aibu ivuvuL/imiL 
ROUND qualifier, 87 
Rounding 

controlling with OPTION, 249 

controlling with SCALE, 105 

DECIMAL values, 87, 249 

in numeric strings, 342, 344t, 347, 349 

NUM$, 339 

with PRINT, 252 

with PRINT USING, 255 
RSET, 274 

RSTS/E SYS calls, 369 
RUN, 102 to 103 

BASIC-PLUS-2 qualifiers, 90t 

DEBUG qualifier, 381 
Run-Time Library, 87 
RUNNH, 102 

See also RUN 



SAVE, 104 

with RENAME, 95 
Saving programs 

with REPLACE, 97 

with SAVE, 104 
%SBTTL, 126 
SCALE, 105 
Scale factor 

setting with OPTION, 249 

Setting With S<~ All, iuj 

SCRATCH, 106, 275 
SEG$, 358 

Segmented keys, 244 
SELECT, 276 to 277 

transferring control into, 236, 237 
Semicolon (;) 

in INPUT, 199 

in INPUT LINE, 202 

in LINPUT, 207 

in MAT PRINT, 224 

in PRINT, 251 
SEQ qualifier, 93 
SEQUENCE, 107 
Sequential files 

deleting records in, 275 

finding records in, 173 

NOSPAN clause, 243 

opening, 240 

record size in, 242 



Sequential files (Cont.) 
retrieving records in, 191 
SEQ qualifier, 93 
updating, 289 

writin° records to 251 258 
SET, 108 

BASIC-PLUS-2 qualifiers, 90t 
BUILD default, 48 
qualifier format, 83 
VAX-11 BASIC qualifiers, 84t 
Setting defaults 
for data types, 1 3 
with BRLRES, 46 
with DSKLIB, 55 
with LIBRARY, 73 
with ODLRMS, 80 
with OPTION, 248 
with RMSRES, 100 
with SCALE, 105 
with SET, 108 
SETUP qualifier, 87 
SGN, 359 
SHOW, 109 to 110 
SHOW qualifier 
CDD_DEFINITIONS, 88, 120 
ENVIRONMENT, 88 
INCLUDE, 88, 120 
MAP, 88 
OVERRIDE, 88 
SI, 24 
SIN, 360 
Sine, 360 

SINGLE data type, 1 1 
SINGLE qualifier, 88, 94 
Single-line 
DEF, 149 
DEF*, 153 

loops, 179, 288, 292 
statements, 4 
Single-statement lines, 4 
Size 
of numeric data, 1 2 
of STRING data, 1 1 
SLEEP, 278 
SO, 24 
SP, 24 
SPACES, 361 
Spacing in keywords, 4 
SQR, 362 
SQRT, 362 
Square roots, 362 
Statement modifiers 
FOR, 179 
IF, 197, 198 
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Statement modifiers (Cont.) 

UNLESS, 286 

UNTIL, 288 

WHILE, 292 
Statements 

block, 162, 164, 179, 197, 264, 277 

BP2 compatible, 85 

components of, 3 

continued, 4, 5 

data typing, 14 

declarative, 145 

declining, 85, 91 

empty, 10 

executable, 3 

execution of, 5 

format of, 3 

labelling of, 2 

multi-statement lines, 5 to 7 

nonexecutable, 3, 8, 141, 143, 147, 159, 

168, 211, 214, 267 
order of, 8, 98 
processing of, 8 
single-line, 4 
Static 
arrays, 158, 159 
mapping, 210 
storage, 139, 210, 269 
STATUS debugger command, 398 to 399 
STATUS function, 363 to 364 

VAX-1 1 BASIC STATUS bits, 364t 
STEP clause, 1 79 
STEP debugger command, 400 
STOP, 279 
See also CONTINUE command 
with RUN, 103 
Stopping program execution, 53, 279, 383, 

400 
Storage 
allocating with REMAP, 268 
COMMON and MAP, 141, 211 
dynamic, 213, 268, 269 
for arrays, 1 59 

for FILL items, 141t, 227, 268 
for RECORD structures, 264 
for VARIANT fields, 265 
in COMMON, 142 
in MAP, 211 
of data, 1 2 
of DECIMAL data, 1 1 
of RFAdata, 12 
of STRING data, 11 
shared, 139, 210 
static, 139, 210, 269 



STR$, 365 

String arithmetic functions 

DIF$, 309 

PLACES, 342 

PROD$, 347 

QUO$, 349 

SUM$, 367 
String constants, 18 to 19 
STRING data type, 1 1 

length, 12 

storage of, 1 1 
STRING debugger command, 401 
String expressions, 34 

relational, 36, 37 
String functions, 304 

ASCII, 295 

EDIT$, 311 

INSTR, 322 

LEFTS, 326 

LEN, 327 

MID$, 335 

POS, 345 

RIGHTS, 356 

SEG$, 358 

SPACES, 361 

STRINGS, 366 

TRM$, 376 

with NOSETUP, 87 

XLATE, 379 
String literals, 37 

continuing, 5 

delimiter, 18 

in PRINT USING format fieid, 257 

processing of, 10 

quotations marks in, 18 
String relational expressions 

evaluation of, 36 

operators, 37t, 37 
String variables, 27 

formatting storage, 209, 274 

in INPUT, 200 

in INPUT LINE, 203 

in LET, 206 

in LINPUT, 208 

with NOSETUP, 87 
STRINGS, 366 
Strings 

comparing, 36, 300 

concatenating, 5, 30, 34, 88 

converting, 136 

creating, 361, 366 

editing, 311, 376 

extracting substrings, 326, 335, 356, 358 

finding length, 327 
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Strings (Cont.) 

finding substrings, 322, 345 

justifying with FORMATS, 318 

justifying with LSET, 209 

justifying with PRINT USING, 256 

justifying with RSET, 274 

numeric, 300, 309, 325, 342, 347, 349, 
354, 367, 377, 378 

suffix character, 1 3 
SUB, 280 to 283 

BASIC-PLUS-2 parameter passing 
mechanisms, 1 33t 

parameters, 281 

VAX-1 1 BASIC parameter passing 
mechanisms, 132t 
SUBEND, 284 

See also END 
SUBEXIT, 285 

See a/so EXIT 
Subprograms 

calling, 129 

declaring, 166 

ending, 162, 184, 281 

error handling in, 163, 164, 185, 233 

exiting, 164 

FUNCTION, 183 

naming, 130, 281 

recursion in, 132, 282 

returning from, 273 

SUB, 280 
Subroutines 

external, 166 

GOSUB, 195 

RETURN, 273 
Subscripted variables, 27 to 29 

format of, 28 

range checking, 84, 249 

subscript range, 28 
Subscripts, 27 

range of, 28 
SUBSTITUTE editing command, 66 to 67 
Substrings 

extracting, 326, 335, 356, 358 

finding, 322, 345 
Suffix characters 

integer, 13 

string, 13 
SUM$, 367 

Suspending program execution, 278 
SWAP%, 368 

SYNTAX_CHECK qualifier, 88, 94 
SYS, 369 to 370 

VAX-1 1 BASIC subset, 369t 
System command, 49 



TAB, 371 
TAN, 372 

I dl IgCML, J/ Z. 

Template, 264 
TEMPORARY clause, 242 
Tensor, 28 
Terminal 

printing to, 251 
Terminal control functions 

ECHO, 310 

NOECHO, 336 

RCTRLO, 353 

TAB, 371 
Terminal-format files, 244 

input from, 199, 202, 207, 219, 221 

margin, 215, 232 

writing records to, 223, 251 
Terminating 

automatic sequencing, 107 

comment fields, 8 

compilation, 1 13 

DATA statements, 1 43 

program lines, 1, 7, 10 

REM statements, 9, 267 
THEN clause, 197 
TIME, 373 to 374 

function values, 374t 
TIMES, 375 
%TITLE, 127 

TRACE debugger command, 402 
TRACEBACK qualifier, 88 
Trailing minus sign field 

hi i ixiiNi UjiiNvj njundi iiviu, Z.~/~i 

Transferring control 

into DEF functions, 151, 236, 237 

into DEF* functions, 155 

into FOR-NEXT loops, 180, 195, 196, 236, 

237 
into SELECT blocks, 236, 237 
into UNTIL loops, 195, 196, 236, 237 
into WHILE loops, 195, 196, 236, 237 
to a label, 195, 196, 236, 237 
to comment fields, 8 
to multi-statement lines, 5 
to REM, 9 
with CALL, 129 
with" CHAIN, 134 
with GOSUB, 195 
with GOTO, 196 
with IF, 197 
with ON-GOSUB, 236 
with ON-GOTO, 237 
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Transferring control (Cont.) 
with RESUME, 203, 208, 272 
with RETURN, 273 

Transferring data 
with MOVE, 227 

Translating rhptrz*rtar cptc 37Q 

Transposing arrays, 218 
Trigonometric functions 

ATN, 296 

COS, 301 

SIN, 360 

TAN, 372 
TRM$, 376 
TRN, 218 
Truncation 

in numeric strings, 342, 344t, 347, 349 

in PRINT USING, 256 

with FIX, 317 
Truth tables, 38t 
Truth tests 

in logical expressions, 38 

in relational expressions, 35 

in string relational expressions, 36 
TYPE_DEFAULT qualifier, 89, 94 



u 



UNBREAK debugger command, 403 to 404 
Unconditional branching 

with GOSUB, 195 

with GOTO, 196 
Unconditional loops, 179 
Underscore (_) 

in PRINT USING format field, 255 

in variable names, 25 
UNLESS, 286 
UNLOCK, 287 
UNLOCK EXPLICIT clause, 173, 175, 191, 

245 
Unlocking records, 245 

with FREE, 182 

with UNLOCK, 287 
UNSAVE, 1 1 1 
UNTIL clause, 180 
UNTIL loops, 231 

error handling in, 272 

exiting, 164 

explicit iteration of, 204 

transferring control into, 195, 196, 236, 237 
UNTIL statement, 288 
UNTRACE debugger command, 405 
UPDATE, 289 to 290 

with UNLOCK, 287 
Updating records, 289 



Uppercase letters 

in EDIT, 58 

in FIND editing command, 64 

in PRINT USING, 256 

in SUBSTITUTE editing command, 66 

processing of, 10 
User-defined functions, 149, 153 
USEROPEN clause, 240, 243 



VAL, 377 
VAL%, 378 
Variable names 

in COMMON, 142 

in MAP, 211, 212 

in MAP DYNAMIC, 213 

in REMAP, 268 

rules for, 25 to 26 
Variables, 25 to 29 

assigning values to, 199, 202, 206, 207, 
261, 393 

declaring, 145 

definition of, 25 

explicitly declared, 27 

external, 166 

floating-point, 26 

implicitly declared, 26 to 27 

in MOVE, 228 

in SUB subprograms, 282 

initialization of, 29, 142, 147, 212 

integer, 27 

loop, 179 

naming, 25 to 26 

string, 27, 200, 203, 206, 208 

subscripted, 27 to 29 
% VARIANT, 128 

in %IF, 117 

in %LET, 121 
Variant, 264 
VARIANT clause, 264 
VARIANT qualifier, 89, 94, 128 
VAX-1 1 BASIC STATUS bits, 364t 
VAX-1 1 BASIC subset of RSTS/E SYS calls 

369t 
Vector, 28 

Version identification, 115 
VIR qualifier, 94 
Virtual address 

finding, 328 
Virtual arrays, 147, 158, 159 

initialization of, 29, 160 

padding in, 160 

with FIELD, 170 
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Virtual arrays (Cont.) 
with NOSETUP, 88 

Virtual files 
record size, 242 



ViR qualifier, 



with RESTORE, 271 
VT, 24 

w 



WORD data type, -11 


WORD qualifier, 89, 94 


Writing records 


by RECORD number, 258 


com sontiai !\/ 9 S& 


with PRINT, 251 


with PUT, 258 


with UPDATE, 289 



WAIT, 291 

WARNINGS qualifier, 89 
WHILE clause, 180 
WHILE loops, 231 

error handling in, 272 

exiting, 164 

explicit iteration of, 204 

transferring control into, 195, 196, 236, 237 
WHILE statement, 292 
Width 

margin, 215, 232, 251, 334 

of listing file, 94 
WIDTH qualifier, 94 
WINDOWSIZE clause, 242 



XLATE, 379 
XOR, 38 



ZER, 217 
Zero 

array element, 28, 159, 218, 220, 222, 224, 
226, 228 

blank-if-zero field, 255 

in PRINT USING format field, 255 
Zero-fill field 

in PRINT USING, 255 
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In Continental USA In Canada In New Hampshire, 
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□ Occasional programmer (experienced) 

□ User with little programming experience 

□ Student programmer 

□ Other (please specify) _ 



Name_ 



_Date_ 



Organization. 
Street 



Zip Code 

Cirv -State ^ or 

uiy Country 



■Do Not Tear - Fold Here and Tape 




No Postage 

Necessary 

if Mailed in the 

United States 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT N0.33 MAYNARD MASS. 



POSTAGE WILL BE PAID BY ADDRESSEE 



ATTN: BSSG Publications ZK01-3/J35 
DIGITAL EQUIPMENT CORPORATION 
110 SPIT BROOK ROAD 
NASHUA, N.H. 03062 




•Do Not Tear - Fold Here and Tape 



-a 

O 

Q 

M 

e 
o 



3 



